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:

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

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

Common Endpoints

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

Date Filtering

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

Pagination

Request Parameters

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",
    "details": "Detailed description",
    "client_id": 123,
    "tickettype_id": 1,
    "status_id": 1,
    "priority_id": 2
  }
]

Note: HaloPSA expects an array for POST operations, even for single items.

Read (GET)

Single entity:

GET /api/Tickets/54321

List with filters:

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

Update (POST with ID)

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

[
  {
    "id": 54321,
    "summary": "Updated summary",
    "status_id": 2
  }
]

Note: Include the id field to update an existing record.

Delete (DELETE)

DELETE /api/Tickets/54321

Note: Not all entities support deletion. Check entity documentation.

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "validation_error",
  "message": "Invalid field value",
  "details": [
    {
      "field": "status_id",
      "message": "Status ID 999 does not exist"
    }
  ]
}

Error Handling Pattern

function handleApiError(response, data) {
  switch (response.status) {
    case 400:
      console.log('Validation Error:', data.message);
      if (data.details) {
        data.details.forEach(d => {
          console.log(`  Field: ${d.field} - ${d.message}`);
        });
      }
      break;

    case 401:
      console.log('Authentication failed - refreshing token');
      return refreshToken().then(() => retryRequest());

    case 403:
      console.log('Permission denied. Check API application permissions.');
      break;

    case 404:
      console.log('Resource not found');
      break;

    case 429:
      const retryAfter = response.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);
      break;

    default:
      console.log('API Error:', data);
  }
}

Scopes and Permissions

Available Scopes

When creating an API application, configure these permissions:

Minimum Recommended Permissions

For typical MSP operations:

• View Customers
• View Support Tickets
• Add Time Entries
• Create Support Tickets
• View Assets

Best Practices

1. Cache access tokens - Tokens are valid for the expires_in duration
2. Use tenant parameter - Required for cloud-hosted instances
3. Implement retry logic - Handle rate limits and transient errors
4. Batch operations - Group related requests with delays
5. Use specific scopes - Request only needed permissions
6. Handle token expiry - Refresh before expiration
7. Log API calls - Enable debugging and audit trails
8. Validate before sending - Check required fields client-side
9. Use pagination - Never fetch unbounded result sets
10. Monitor rate limits - Track and respect limits

Common Issues

"Invalid grant" Error

Cause: Client credentials are incorrect or application is disabled.

Fix:

1. Verify Client ID and Secret
2. Check application is active in HaloPSA
3. Ensure permissions are configured

"Tenant not found" Error

Cause: Incorrect or missing tenant parameter.

Fix:

1. For cloud-hosted: Use company name from URL
2. For self-hosted: Leave tenant empty

401 After Successful Token

Cause: Token used with wrong server URL.

Fix: Ensure Resource Server URL is correct (/api path).

Related Skills

• HaloPSA Tickets - Ticket management
• HaloPSA Clients - Client management
• HaloPSA Assets - Asset tracking
• HaloPSA Contracts - Contract management