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.

Anti-triggers

"ConnectWise" is an umbrella brand over three products with three unrelated APIs. Loading the wrong one produces auth failures that read like permission problems:

• ConnectWise PSA (Manage) — hosted at api-*.myconnectwise.net/{codebase}/apis/3.0/, authenticated with public/private key plus a clientId header, and filtered with plural conditions=. An Automate bearer token will not authenticate against it. Use connectwise-psa-api-patterns.
• ConnectWise CPQ (Sell/Quosal) — its own host and credential set again; use connectwise-cpq-api-patterns.

Key Concepts

API Base URL

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

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

Authentication Methods

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

Token Refresh

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

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

Pagination

ConnectWise Automate uses offset-based pagination with lowercase page/pageSize query parameters (max pageSize is 1000):

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

Track pagination via response headers rather than assuming page count:

See references/examples.md for a complete fetchAllComputers pagination loop that reads X-Total-Pages and paces requests to respect rate limits.

Filtering with OData

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

Filter Operators

Logical Operators

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 (~60 requests per minute, ~10 concurrent; daily limits vary by config). Exceeding them returns HTTP 429.

On a 429, read Retry-After and wait before retrying; on a 5xx, retry with exponential backoff. See references/examples.md for a requestWithRetry implementation.

Error Handling

Common statuses: 401 (token expired - re-authenticate), 403 (permission denied), 404 (not found), 429 (rate limited - see Rate Limiting above), 500/503 (retry with backoff). Error responses are shaped as { "error": { "code", "message", "details" } }.

See references/errors.md for the complete HTTP status code table, error response format, and a reusable AutomateAPIError/handleApiResponse error-handling pattern.

Complete API Client

A full ConnectWiseAutomateClient class that combines token caching, retry-with-backoff, and pagination-aware request methods (getComputers, getClients, getAlerts, runScript) is available in references/examples.md.

Best Practices

1. Cache tokens - Reuse tokens until near expiry
2. Use integrator credentials - More reliable for automation
3. Implement rate limiting - Stay under ~60 req/min
4. Use pagination - Always handle multiple pages
5. Filter at API level - Use condition parameter, not client-side filtering
6. Handle errors gracefully - Implement retry with backoff
7. URL-encode conditions - Prevent syntax errors
8. Log API calls - Enable debugging and audit trails
9. Validate inputs - Check data before sending

Common Query Patterns

Get All Online Computers for Client

const computers = await client.getComputers(
  "ClientID = 100 and Status = 'Online'"
);

Get Critical Alerts

const alerts = await client.getAlerts(
  "Severity >= 3 and Status in ('New','Active')"
);

Search Computers by Name

const computers = await client.getComputers(
  "Name contains 'DC'"
);

Get Recently Offline Computers

const yesterday = new Date(Date.now() - 86400000).toISOString();
const computers = await client.getComputers(
  `Status = 'Offline' and LastContact >= '${yesterday}'`
);

Batch Operations with Rate Limiting

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);

    // Process batch in parallel
    const batchResults = await Promise.all(
      batch.map(item => processor(item).catch(e => ({ error: e.message })))
    );
    results.push(...batchResults);

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

  return results;
}

Related Skills

• ConnectWise Automate Computers - Computer management
• ConnectWise Automate Clients - Client management
• ConnectWise Automate Scripts - Script execution
• ConnectWise Automate Monitors - Monitor management
• ConnectWise Automate Alerts - Alert management