HaloPSA API Patterns

HaloPSA API Patterns

Overview

The HaloPSA REST API provides access to all PSA entities including tickets, clients, assets, contracts, and more. This skill covers OAuth 2.0 Client Credentials authentication, tenant configuration, query patterns, pagination, and error handling.

Authentication

OAuth 2.0 Client Credentials Flow

HaloPSA uses OAuth 2.0 Client Credentials flow for API authentication. This is different from basic API key authentication - you must obtain an access token before making API requests.

Server URLs

HaloPSA has two server URLs:

| Server | Purpose | Example | |--------|---------|---------| | Authorization Server | Token endpoint | https://yourcompany.halopsa.com/auth | | Resource Server | API endpoints | https://yourcompany.halopsa.com/api |

Find these in Configuration > Integrations > HaloPSA API > API Details.

Token Acquisition

Token Endpoint:

POST https://{base_url}/auth/token?tenant={tenant_name}

Request:

curl -X POST "https://yourcompany.halopsa.com/auth/token?tenant=yourcompany" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=all"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "all"
}

Token Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | grant_type | Yes | Must be client_credentials | | client_id | Yes | Application Client ID | | client_secret | Yes | Application Client Secret | | scope | Yes | Permissions scope (use all or specific scopes) | | tenant | Conditional | Required for cloud-hosted instances (query parameter) |

Environment Configuration

# Required environment variables
export HALOPSA_CLIENT_ID="your-client-id"
export HALOPSA_CLIENT_SECRET="your-client-secret"
export HALOPSA_BASE_URL="https://yourcompany.halopsa.com"
export HALOPSA_TENANT="yourcompany"  # Leave empty for self-hosted

Token Management

class HaloPSAAuth {
  constructor(clientId, clientSecret, baseUrl, tenant) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.baseUrl = baseUrl;
    this.tenant = tenant;
    this.accessToken = null;
    this.tokenExpiry = null;
  }

  async getAccessToken() {
    // Return cached token if still valid (with 5 min buffer)
    if (this.accessToken && this.tokenExpiry > Date.now() + 300000) {
      return this.accessToken;
    }

    const tokenUrl = this.tenant
      ? `${this.baseUrl}/auth/token?tenant=${this.tenant}`
      : `${this.baseUrl}/auth/token`;

    const response = await fetch(tokenUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret,
        scope: 'all'
      })
    });

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

    const data = await response.json();
    this.accessToken = data.access_token;
    this.tokenExpiry = Date.now() + (data.expires_in * 1000);

    return this.accessToken;
  }
}

API Request Structure

Making Authenticated Requests

GET /api/Tickets
Authorization: Bearer {access_token}
Content-Type: application/json

Base URL Structure

| Instance Type | URL Pattern | |---------------|-------------| | Cloud-hosted | https://{company}.halopsa.com/api | | Self-hosted | https://{your-server}/api |

Common Endpoints

| Resource | Endpoint | Methods | |----------|----------|---------| | Tickets | /api/Tickets | GET, POST | | Clients | /api/Client | GET, POST | | Assets | /api/Asset | GET, POST | | Contracts | /api/ClientContract | GET, POST | | Users | /api/Users | GET, POST | | Actions | /api/Actions | GET, POST | | Sites | /api/Site | GET, POST |

Query Parameters

Filtering Results

HaloPSA uses query parameters for filtering:

GET /api/Tickets?client_id=123&status_id=1&tickettype_id=5

Common Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | client_id | int | Filter by client | | status_id | int | Filter by status | | tickettype_id | int | Filter by ticket type | | agent_id | int | Filter by assigned agent | | search | string | Text search | | order | string | Sort field | | orderdesc | bool | Sort descending |

Date Filtering

GET /api/Tickets?dateoccurred_start=2024-01-01&dateoccurred_end=2024-01-31

Pagination

Request Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | page_no | int | 1 | Page number (1-based) | | page_size | int | 50 | Results per page | | count | int | - | Total count (in response) |

Paginated Request

GET /api/Tickets?page_no=1&page_size=100

Response Structure

{
  "record_count": 523,
  "tickets": [
    { "id": 1, "summary": "..." },
    { "id": 2, "summary": "..." }
  ]
}

Pagination Pattern

async function fetchAllTickets(filters = {}) {
  const allTickets = [];
  let pageNo = 1;
  const pageSize = 100;
  let hasMore = true;

  while (hasMore) {
    const params = new URLSearchParams({
      ...filters,
      page_no: pageNo,
      page_size: pageSize
    });

    const response = await fetch(`${baseUrl}/api/Tickets?${params}`, {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });

    const data = await response.json();
    allTickets.push(...data.tickets);

    hasMore = data.tickets.length === pageSize;
    pageNo++;
  }

  return allTickets;
}

Rate Limiting

Rate Limit Behavior

HaloPSA implements rate limiting to protect the API. When rate limited:

• HTTP Status: 429 Too Many Requests
• Retry-After header may be present

Rate Limit Response

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 60 seconds.",
  "retry_after": 60
}

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 = parseInt(response.headers.get('Retry-After')) || 60;
        const jitter = Math.random() * 5000;
        console.log(`Rate limited. Waiting ${retryAfter}s + jitter`);
        await sleep(retryAfter * 1000 + jitter);
        continue;
      }

      if (response.status === 401) {
        // Token expired, refresh and retry
        await refreshToken();
        options.headers['Authorization'] = `Bearer ${accessToken}`;
        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);
    }
  }
}

Batch Processing

async function batchProcess(items, batchSize = 25, delayMs = 2000) {
  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(item => processItem(item))
    );
    results.push(...batchResults);

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

  return results;
}

CRUD Operations

Create (POST)

POST /api/Tickets
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "summary": "New ticket summary",
    "deta