Datto RMM API Patterns

Datto RMM API Patterns

Overview

The Datto RMM REST API v2 provides programmatic access to device management, alerts, sites, jobs, and audit data. This skill covers authentication, platform selection, pagination, error handling, and performance optimization patterns.

Key Concepts

Platforms

Datto RMM operates across 6 regional platforms. You must use the correct base URL for your account:

Platform	Region	API Base URL
pinotage	US/Canada	https://pinotage-api.centrastage.net
merlot	US/Canada	https://merlot-api.centrastage.net
concord	EU	https://concord-api.centrastage.net
vidal	EU	https://vidal-api.centrastage.net
zinfandel	APAC	https://zinfandel-api.centrastage.net
syrah	UK	https://syrah-api.centrastage.net

Authentication Flow

Datto RMM uses OAuth 2.0 client credentials flow:

┌─────────────┐     1. POST /auth/oauth/token     ┌─────────────────┐
│   Client    │ ──────────────────────────────>   │  Datto RMM API  │
│             │     (API Key + Secret)            │                 │
│             │ <────────────────────────────────  │                 │
└─────────────┘     2. Access Token (100h TTL)    └─────────────────┘
       │
       │  3. API Request with Bearer Token
       ▼
┌─────────────────────────────────────────────────────────────────┐
│  GET /api/v2/devices                                            │
│  Authorization: Bearer <access_token>                           │
└─────────────────────────────────────────────────────────────────┘

Token Lifecycle

• Token Expiry: 100 hours (approximately 4 days)
• Refresh Strategy: Request new token before expiry
• Storage: Cache token securely, reuse until near expiry

Field Reference

OAuth Token Request

POST https://{platform}-api.centrastage.net/auth/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username={API_KEY}&password={API_SECRET}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 360000
}

API Request Headers

Header	Value	Description
Authorization	Bearer {token}	OAuth 2.0 access token
Content-Type	application/json	Required for POST/PUT/PATCH
Accept	application/json	Response format

Environment Variables

export DATTO_API_KEY="your-api-key"
export DATTO_API_SECRET="your-api-secret"
export DATTO_PLATFORM="merlot"  # pinotage, merlot, concord, vidal, zinfandel, syrah

API Patterns

Token Acquisition

async function getAccessToken(platform, apiKey, apiSecret) {
  const response = await fetch(
    `https://${platform}-api.centrastage.net/auth/oauth/token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        grant_type: 'password',
        username: apiKey,
        password: apiSecret
      })
    }
  );

  if (!response.ok) {
    throw new Error(`Authentication failed: ${response.status}`);
  }

  const data = await response.json();
  return {
    token: data.access_token,
    expiresAt: Date.now() + (data.expires_in * 1000)
  };
}

Pagination

Datto RMM uses cursor-based pagination with nextPageUrl:

Request:

GET /api/v2/devices?max=250
Authorization: Bearer {token}

Response:

{
  "devices": [...],
  "pageDetails": {
    "count": 250,
    "nextPageUrl": "/api/v2/devices?max=250&page=xyz123",
    "prevPageUrl": null
  }
}

Pagination Constants:

Parameter	Max Value	Default
max	250	50

Efficient Pagination Pattern:

async function fetchAllDevices(token, platform) {
  const allDevices = [];
  let url = `/api/v2/devices?max=250`;

  while (url) {
    const response = await fetch(
      `https://${platform}-api.centrastage.net${url}`,
      {
        headers: { Authorization: `Bearer ${token}` }
      }
    );

    const data = await response.json();
    allDevices.push(...data.devices);

    // Get next page URL from response
    url = data.pageDetails?.nextPageUrl || null;
  }

  return allDevices;
}

Rate Limiting

Datto RMM enforces strict rate limits:

Limit Type	Threshold	Consequence
Requests per minute	600	HTTP 429
Sustained high volume	-	IP blocking (1 hour)

Rate Limit Headers:

Header	Description
X-RateLimit-Limit	Max requests per window
X-RateLimit-Remaining	Remaining requests
X-RateLimit-Reset	Seconds until reset

Retry Strategy:

async function requestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        console.log(`Rate limited. Waiting ${retryAfter}s...`);
        await sleep(retryAfter * 1000);
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      // Exponential backoff with jitter
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await sleep(delay);
    }
  }
}

Timestamp Handling

Datto RMM uses Unix milliseconds for all timestamps:

// Convert ISO date to Datto timestamp
const dattoTimestamp = new Date('2024-02-15T10:00:00Z').getTime();
// Result: 1707991200000

// Convert Datto timestamp to Date
const jsDate = new Date(1707991200000);
// Result: 2024-02-15T10:00:00.000Z

// Calculate timestamp for "last 24 hours"
const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);

Timestamp Query Example:

GET /api/v2/alerts/open?since=1707991200000

Workflows

Complete API Request Flow

class DattoRMMClient {
  constructor(platform, apiKey, apiSecret) {
    this.baseUrl = `https://${platform}-api.centrastage.net`;
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.token = null;
    this.tokenExpiry = 0;
  }

  async ensureToken() {
    if (!this.token || Date.now() > this.tokenExpiry - 60000) {
      const auth = await getAccessToken(
        this.platform,
        this.apiKey,
        this.apiSecret
      );
      this.token = auth.token;
      this.tokenExpiry = auth.expiresAt;
    }
    return this.token;
  }

  async request(endpoint, options = {}) {
    const token = await this.ensureToken();

    const response = await requestWithRetry(
      `${this.baseUrl}${endpoint}`,
      {
        ...options,
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json',
          ...options.headers
        }
      }
    );

    if (!response.ok) {
      throw new DattoAPIError(response);
    }

    return response.json();
  }

  async getDevices() {
    return this.request('/api/v2/devices?max=250');
  }

  async getDevice(uid) {
    return this.request(`/api/v2/device/${uid}`);
  }

  async getAlerts() {
    return this.request('/api/v2/alerts/open');
  }
}

Site-Scoped Queries

Many endpoints support site-level filtering:

# Get devices for a specific site
GET /api/v2/site/{siteUid}/devices

# Get alerts for a specific site
GET /api/v2/site/{siteUid}/alerts/open

# Get resolved alerts for a site
GET /api/v2/site/{siteUid}/alerts/resolved

Error Handling

HTTP Status Codes

Code	Meaning	Action
200	Success	Process response
201	Created	Entity created successfully
400	Bad Request	Check request format/parameters
401	Unauthorized	Refresh token and retry
403	Forbidden	Check API permissions
404	Not Found	Entity doesn't exist
429	Rate Limited	Wait and retry with backoff
500	Server Error	Retry with backoff

Error Response Format

{
  "errorCode": "INVALID_PARAMETER",
  "message": "The device UID is not valid",
  "details": {
    "field": "deviceUid",
    "value": "invalid-uid"
  }
}

Error Handling Pattern

class DattoAPIError extends Error {
  constructor(response, data) {
    super(data?.message || `API Error: ${response.status}`);
    this.status = response.status;
    this.errorCode = data?.errorCode;
    this.details = data?.details;
  }
}

async function handleApiResponse(response) {
  if (response.ok) {
    return response.json();
  }

  const data = await response.json().catch(() => ({}));

  switch (response.status) {
    case 401:
      throw new DattoAPIError(response, {
        ...data,
        message: 'Authentication failed. Check API credentials or refresh token.'
      });

    case 403:
      throw new DattoAPIError(response, {
        ...data,
        message: 'Permission denied. Verify API key has required permissions.'
      });

    case 404:
      throw new DattoAPIError(response, {
        ...data,
        message: 'Resource not found. Check UID validity.'
      });

    case 429:
      throw new DattoAPIError(response, {
        ...data,
        message: 'Rate limited. Implement backoff strategy.'
      });

    default:
      throw new DattoAPIError(response, data);
  }
}

Best Practices

1. Cache tokens - Reuse tokens until near expiry (100 hours)
2. Use correct platform - Verify your account's platform before making requests
3. Respect rate limits - Stay under 600 req/min to avoid IP blocking
4. Use pagination - Always handle nextPageUrl for large result sets
5. Handle timestamps - Datto uses Unix milliseconds, not seconds
6. Implement retry logic - Use exponential backoff for transient errors
7. Cache reference data - Sites and account info change infrequently
8. Scope queries to sites - Use site-level endpoints when possible
9. Monitor rate limit headers - Track remaining requests proactively
10. Log API calls - Enable debugging and audit trails

Common Query Patterns

Filter by Time Range

// Alerts in last 24 hours
const since = Date.now() - (24 * 60 * 60 * 1000);
const url = `/api/v2/alerts/open?since=${since}`;

Device Lookups

// By hostname (requires fetching all and filtering)
const devices = await client.getDevices();
const device = devices.find(d =>
  d.hostname.toLowerCase() === hostname.toLowerCase()
);

// By UID (direct lookup)
const device = await client.getDevice(deviceUid);

Batch Operations

async function batchProcess(items, processor, { batchSize = 10, delayMs = 1000 }) {
  const results = [];

  for (let i = 0; i < items.length; i += batchSize) {
    const batch = items.slice(i, i + batchSize);
    const batchResults = await Promise.all(batch.map(processor));
    results.push(...batchResults);

    // Respect rate limits between batches
    if (i + batchSize < items.length) {
      await sleep(delayMs);
    }
  }

  return results;
}

Related Skills

• Datto RMM Devices - Device management
• Datto RMM Alerts - Alert handling
• Datto RMM Sites - Site management
• Datto RMM Jobs - Job execution