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 Endpoint

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

Form-encoded body with grant_type=client_credentials, client_id, client_secret, and scope. The tenant query parameter is required for cloud-hosted instances and omitted for self-hosted. Tokens are returned with an expires_in (typically 3600s) - cache them and refresh with a buffer before expiry.

See references/auth.md for the full token request/response, parameter table, environment configuration, a caching token-manager class, and the scope catalog.

API Request Structure

Making Authenticated Requests

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

Base URL Structure

Filtering

Filters are plain query parameters, e.g. GET /api/Tickets?client_id=123&status_id=1&tickettype_id=5. Date ranges use _start / _end suffixes on the date field (dateoccurred_start, dateoccurred_end).

See references/api.md for the endpoint catalog, the full query-parameter table, and complete CRUD request shapes.

Pagination

Request Parameters

Paginated Request

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

Response Structure

Results come back under a key named for the entity (not a generic data/items key), alongside record_count:

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

See references/examples.md for a full pagination loop, retry, and batch-processing implementations.

CRUD Conventions

• POST bodies are always arrays, even for a single record.
• Updates reuse POST on the collection endpoint - include the id field to update an existing record instead of creating one.
• DELETE is DELETE /api/{Entity}/{id}, but not all entities support it.

Rate Limiting

HaloPSA rate limits return HTTP 429 Too Many Requests, sometimes with a Retry-After header and a JSON body carrying retry_after seconds. Back off for the indicated interval plus jitter, and space bulk operations into batches with a delay between them.

Error Handling

HTTP Status Codes

Validation errors (400) return a details array naming the offending field and reason. See references/api.md for the error and rate-limit response shapes, and references/examples.md for a status-code dispatch handler.

Best Practices

1. Cache access tokens - Tokens are valid for the expires_in duration; refresh before expiry rather than per-request
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. Use pagination - Never fetch unbounded result sets

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