NinjaOne API Patterns

Overview

The NinjaOne Public API uses OAuth 2.0 for authentication and provides RESTful endpoints for all platform operations.

Regional Endpoints

Use the base URL matching your NinjaOne instance region.

Authentication

OAuth 2.0 Flow

NinjaOne uses OAuth 2.0 with the following scopes:

• monitoring - Read monitoring data
• management - Manage devices and organizations
• control - Remote control capabilities

Getting Access Token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=monitoring management control

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "monitoring management control"
}

Using the Token

Include in all API requests:

GET /api/v2/organizations
Authorization: Bearer eyJ...

Token Refresh

Tokens expire after the expires_in period. Request a new token before expiration.

Creating API Credentials

1. Navigate to Administration > Apps > API
2. Click Add to create new API credentials
3. Enter a name for the integration
4. Select required scopes
5. Copy Client ID and Client Secret
6. Store credentials securely

Making Requests

Standard GET Request

GET /api/v2/organizations
Authorization: Bearer {token}
Accept: application/json

POST with Body

POST /api/v2/organizations
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "name": "New Organization",
  "description": "Description here"
}

PATCH for Updates

PATCH /api/v2/device/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "displayName": "Updated Name"
}

Pagination

NinjaOne uses cursor-based pagination:

Request

GET /api/v2/organizations?pageSize=50

Response

{
  "results": [...],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "abc123xyz"
  }
}

Next Page

GET /api/v2/organizations?pageSize=50&after=abc123xyz

Pagination Pattern

let cursor = null;
let allResults = [];

do {
  const url = cursor
    ? `/api/v2/organizations?pageSize=100&after=${cursor}`
    : '/api/v2/organizations?pageSize=100';

  const response = await fetch(url, { headers });
  const data = await response.json();

  allResults = allResults.concat(data.results);
  cursor = data.pageInfo.hasNextPage ? data.pageInfo.endCursor : null;

} while (cursor);

Rate Limiting

NinjaOne implements rate limiting to ensure API stability:

Headers

Watch for these response headers:

• X-RateLimit-Limit - Max requests per window
• X-RateLimit-Remaining - Requests remaining
• X-RateLimit-Reset - Window reset time

429 Response

When rate limited:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 60
}

Best Practices

1. Implement exponential backoff - Wait longer after each retry
2. Respect Retry-After - Don't retry before indicated time
3. Cache when possible - Reduce unnecessary requests
4. Batch operations - Combine multiple operations when API allows

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "validation_error",
  "message": "Invalid field value",
  "details": {
    "field": "name",
    "issue": "Required field missing"
  }
}

Error Handling Pattern

async function makeRequest(url, options) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After') || 60;
    await sleep(retryAfter * 1000);
    return makeRequest(url, options);
  }

  if (response.status === 401) {
    await refreshToken();
    return makeRequest(url, options);
  }

  if (!response.ok) {
    const error = await response.json();
    throw new ApiError(error.message, response.status);
  }

  return response.json();
}

Webhooks

Configure Webhook

PUT /api/v2/webhook
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["ALERT_TRIGGERED", "DEVICE_OFFLINE"]
}

Remove Webhook

DELETE /api/v2/webhook

Webhook Events

Best Practices

1. Store tokens securely - Never commit credentials
2. Handle token expiration - Refresh before requests fail
3. Use appropriate scopes - Request minimum needed
4. Implement retries - Handle transient failures
5. Log API calls - Debug and audit trail
6. Validate responses - Don't assume success

Related Skills

• Devices - Device endpoints
• Organizations - Organization endpoints
• Alerts - Alert endpoints
• Tickets - Ticketing endpoints