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 |