IT Glue API Patterns

Overview

The IT Glue API follows the JSON:API specification, providing access to organizations, configurations (assets), contacts, passwords, documents, and flexible assets. This skill covers authentication, query building, pagination, error handling, and performance optimization patterns.

Authentication

IT Glue uses API key authentication via the x-api-key header:

GET /organizations
x-api-key: YOUR_API_KEY
Content-Type: application/vnd.api+json

Required Headers:

export IT_GLUE_API_KEY="ITG.your-api-key-here"
export IT_GLUE_REGION="us"  # us, eu, or au

IT Glue operates in multiple regions with separate base URLs — using the wrong one for a customer's account returns 401s that look like a bad key:

JSON:API Structure

Requests and responses follow JSON:API conventions:

{
  "data": {
    "type": "organizations",
    "attributes": {
      "name": "Acme Corporation",
      "organization-type-id": 12345,
      "organization-status-id": 1
    }
  }
}

Field names in attributes are kebab-case (organization-type-id), not camelCase — this trips up integrations ported from other APIs.

API Patterns

Filtering

GET /organizations?filter[name]=Acme
GET /organizations?filter[organization-status-id]=1
GET /configurations?filter[organization-id]=123456

Filters are per-endpoint (not every field is filterable). See references/api.md for the common filter parameter table, multi-filter combining, and PSA-ID cross-platform lookups.

Sorting

GET /organizations?sort=name
GET /organizations?sort=-created-at
GET /configurations?sort=name,-updated-at

No prefix sorts ascending; - prefix sorts descending. See references/api.md for common sort fields per endpoint.

Pagination

GET /organizations?page[size]=50&page[number]=1

Check meta['next-page'] (not total-pages) to decide whether to keep paging — it's null on the last page. See references/examples.md for a full fetch-all-pages pattern and references/api.md for the response metadata shape.

Sideloading with Includes

Retrieve related resources in a single request instead of N+1 calls:

GET /configurations/123?include=organization,configuration-interfaces
GET /organizations/456?include=configurations,contacts,passwords

See references/api.md for the available includes per endpoint and an example response shape.

CRUD and Nested Resources

Standard verbs: POST to create, GET to read, PATCH to update (partial — only send changed attributes), DELETE to remove (not all resource types support it). Resources can also be created/listed scoped to a parent organization via /organizations/:id/relationships/:type. See references/api.md for full request/response examples of each operation.

Rate Limiting

X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2847
X-RateLimit-Reset: 1708012800

A 429 response includes a Retry-After header — respect it rather than a fixed backoff, and add jitter to avoid thundering-herd retries across concurrent jobs. See references/examples.md for a retry-with-backoff implementation.

Error Handling

Validation errors (422) report the failing attribute in error.source.pointer (e.g. /data/attributes/name) — parse it to point users at the exact field. See references/errors.md for the full error response shape and a handling pattern.

Best Practices

1. Use the correct regional endpoint - Matching US/EU/AU wrong silently produces 401s
2. Include related data - Use include to avoid N+1 queries
3. Paginate large results - Use page[size] up to 1000
4. Implement retry logic - Respect Retry-After for 429s and use backoff with jitter
5. Cache reference data - Organization types, configuration types rarely change
6. Filter and sort server-side - Narrow and order results via query params, not client-side

Related Skills

• IT Glue Organizations - Organization management
• IT Glue Configurations - Asset management
• IT Glue Passwords - Secure credential storage
• IT Glue Documents - Documentation management