ConnectWise Automate API Patterns

ConnectWise Automate API Patterns

Overview

The ConnectWise Automate REST API v1 provides programmatic access to computers, clients, scripts, monitors, alerts, and more. This skill covers authentication, token management, pagination, filtering, error handling, and performance optimization patterns.

Key Concepts

API Base URL

https://{automate-server}/cwa/api/v1/

Replace {automate-server} with your Automate server hostname.

Authentication Methods

| Method | Description | Use Case | |--------|-------------|----------| | Integrator | Server-to-server credentials | API integrations, automation | | User + 2FA | User credentials with optional MFA | User-context operations |

Authentication Flow

┌─────────────┐     1. POST /APICredentials     ┌─────────────────────┐
│   Client    │ ─────────────────────────────>  │  Automate Server    │
│             │     (username + password)       │                     │
│             │ <─────────────────────────────  │                     │
└─────────────┘     2. Access Token + Expiry    └─────────────────────┘
       │
       │  3. API Request with Authorization Header
       ▼
┌───────────────────────────────────────────────────────────────────┐
│  GET /cwa/api/v1/Computers                                        │
│  Authorization: Bearer <access_token>                             │
└───────────────────────────────────────────────────────────────────┘

Token Lifecycle

• Token Expiry: Typically 4 hours (configurable on server)
• Refresh Strategy: Request new token before expiry
• Storage: Cache token securely, reuse until near expiry

Field Reference

Environment Variables

# Integrator credentials (recommended for automation)
export CONNECTWISE_AUTOMATE_SERVER="automate.example.com"
export CONNECTWISE_AUTOMATE_USERNAME="integrator-username"
export CONNECTWISE_AUTOMATE_PASSWORD="integrator-password"

# User credentials with optional 2FA
export CONNECTWISE_AUTOMATE_SERVER="automate.example.com"
export CONNECTWISE_AUTOMATE_USER="username"
export CONNECTWISE_AUTOMATE_PASS="password"
export CONNECTWISE_AUTOMATE_2FA="optional-2fa-key"

Token Response Fields

interface TokenResponse {
  AccessToken: string;          // Bearer token for API requests
  TokenType: string;            // "Bearer"
  ExpiresIn: number;            // Seconds until expiry
  RefreshToken: string;         // Token for refresh (if enabled)
  UserID: number;               // Authenticated user ID
  Username: string;             // Authenticated username
}

API Patterns

Token Acquisition - Integrator

POST /cwa/api/v1/APICredentials
Content-Type: application/json

{
  "Username": "{integrator-username}",
  "Password": "{integrator-password}"
}

Response:

{
  "AccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "TokenType": "Bearer",
  "ExpiresIn": 14400,
  "UserID": 1,
  "Username": "integrator"
}

Token Acquisition - User with 2FA

POST /cwa/api/v1/APICredentials
Content-Type: application/json

{
  "Username": "{username}",
  "Password": "{password}",
  "TwoFactorCode": "{6-digit-code}"
}

Request Headers

| Header | Value | Description | |--------|-------|-------------| | Authorization | Bearer {token} | Required for all API requests | | Content-Type | application/json | Required for POST/PUT/PATCH | | Accept | application/json | Response format |

Token Refresh

POST /cwa/api/v1/APICredentials/Refresh
Content-Type: application/json

{
  "RefreshToken": "{refresh-token}"
}

Pagination

ConnectWise Automate uses offset-based pagination:

Pagination Parameters

| Parameter | Type | Default | Max | Description | |-----------|------|---------|-----|-------------| | page | integer | 1 | - | Page number (1-based) | | pageSize | integer | 50 | 1000 | Items per page |

Pagination Request

GET /cwa/api/v1/Computers?page=1&pageSize=100
Authorization: Bearer {token}

Pagination Response Headers

| Header | Description | |--------|-------------| | X-Total-Count | Total number of items | | X-Page | Current page number | | X-Page-Size | Items per page | | X-Total-Pages | Total number of pages |

Efficient Pagination Pattern

async function fetchAllComputers(token, baseUrl) {
  const allComputers = [];
  let page = 1;
  const pageSize = 250;
  let totalPages = 1;

  while (page <= totalPages) {
    const response = await fetch(
      `${baseUrl}/Computers?page=${page}&pageSize=${pageSize}`,
      {
        headers: { Authorization: `Bearer ${token}` }
      }
    );

    // Get pagination info from headers
    totalPages = parseInt(response.headers.get('X-Total-Pages') || '1');

    const computers = await response.json();
    allComputers.push(...computers);

    page++;

    // Respect rate limits
    if (page <= totalPages) {
      await sleep(100);
    }
  }

  return allComputers;
}

Filtering with OData

ConnectWise Automate supports OData-style filtering with the condition parameter.

Filter Operators

| Operator | Description | Example | |----------|-------------|---------| | = | Equal | Status = 'Online' | | != | Not equal | Status != 'Offline' | | > | Greater than | ComputerID > 100 | | < | Less than | TotalMemory < 4096 | | >= | Greater or equal | Severity >= 3 | | <= | Less or equal | DiskFreePercent <= 10 | | contains | String contains | Name contains 'DC' | | startswith | String starts with | Name startswith 'ACME' | | endswith | String ends with | Name endswith '01' | | in | Value in list | Status in ('Online','Offline') |

Logical Operators

| Operator | Description | Example | |----------|-------------|---------| | and | Logical AND | Status = 'Online' and ClientID = 100 | | or | Logical OR | Status = 'Offline' or Status = 'Unknown' | | not | Logical NOT | not (Status = 'Offline') |

Filter Examples

# Computers that are online
GET /cwa/api/v1/Computers?condition=Status = 'Online'

# Computers for a specific client
GET /cwa/api/v1/Computers?condition=ClientID = 100

# Windows servers that are online
GET /cwa/api/v1/Computers?condition=OS contains 'Server' and Status = 'Online'

# Computers with names starting with "ACME"
GET /cwa/api/v1/Computers?condition=Name startswith 'ACME'

# Alerts with severity 3 or higher
GET /cwa/api/v1/Alerts?condition=Severity >= 3

# Active alerts for a client
GET /cwa/api/v1/Alerts?condition=ClientID = 100 and Status in ('New','Active')

# Offline computers with recent contact
GET /cwa/api/v1/Computers?condition=Status = 'Offline' and LastContact >= '2024-02-14'

URL Encoding

Always URL-encode the condition parameter:

const condition = "Status = 'Online' and ClientID = 100";
const url = `/Computers?condition=${encodeURIComponent(condition)}`;

Rate Limiting

ConnectWise Automate enforces rate limits to protect server resources.

Rate Limit Details

| Limit Type | Typical Threshold | Consequence | |------------|-------------------|-------------| | Requests per minute | ~60 | HTTP 429 response | | Concurrent requests | ~10 | Request queuing | | Daily requests | Varies | May require config change |

Rate Limit Headers

| Header | Description | |--------|-------------| | X-RateLimit-Limit | Max requests per window | | X-RateLimit-Remaining | Remaining requests | | X-RateLimit-Reset | Seconds until reset | | Retry-After | Seconds to wait (on 429) |

Rate Limit Handling

async function requestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    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(retryAft