Overview

Customer API

Use company-scoped API keys to authenticate server-to-server requests to the Customer API. This reference is generated from the same contract definitions that publish the OpenAPI document.

OpenAPI JSON Make your first request

Base URL

https://idleatlas.com/api/customer/v1

Auth Header

x-api-key: ia_live_...

Public Docs

https://idleatlas.com/api/customer/v1/openapi.json

1. Create a key

Signed-in company admins can create and revoke API keys in Security Settings. The secret is shown only once when the key is created.

2. Send the header

Include the key in the x-api-key header on every customer API request. Treat the secret like a password.

3. Confirm the company

Start with the organization endpoint to confirm the API key belongs to the company you expect before calling other resources.

Access policy

A valid API key can read company data across the Customer API

Any valid customer API key can read company data across the Customer API, including company details, locations, people, invitations, and roles. Write endpoints do not inherit this automatically and must declare their own authorization requirements.

Authentication

Use API keys for integrations and your signed-in session to manage keys

External integrations should send a company API key in the x-api-key header. Each key is scoped to a single company and only grants access to that company's data.

Endpoints for creating and revoking API keys use a signed-in admin session instead of API key authentication, so company admins can manage credentials in the app.

Rate limiting

Customer API keys are currently limited to 120 requests per 60 seconds. If you hit the limit, the API returns a 429 response and may include a Retry-After header.

Headers

Send JSON and include your key

Keep requests explicit: send JSON bodies where required and include the API key header on every customer API call.

x-api-key: ia_live_********************************
accept: application/json
content-type: application/json

First Request

Check which company your key belongs to

This request confirms which company the API key is connected to.

curl https://idleatlas.com/api/customer/v1/organization \
  -H "x-api-key: ia_live_********************************"

{
  "organization": {
    "id": "org_123",
    "name": "Acme Health",
    "slug": "acme-health",
    "status": "active"
  }
}

Errors

Error responses use a stable envelope

Validation, auth, and lookup failures return a JSON body with an error code and a human-readable message.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

401 Unauthorized

Missing or invalid API key for customer API calls.

403 Forbidden

Signed-in caller lacks permission to manage keys.

404 Not Found

The requested API key does not belong to the active company.

400 Bad Request

JSON input failed validation.

Getting Started

Start here to confirm which company the API key belongs to and retrieve the generated OpenAPI document.

GET/api/customer/v1/openapi.jsonPublic

Get the customer API OpenAPI document

Returns the generated OpenAPI document for the customer API surface.

Tags: Documentation

cURL

curl https://idleatlas.com/api/customer/v1/openapi.json

Responses

200 OpenAPI document.

GET/api/customer/v1/organizationAPI key header (x-api-key)

Get the company linked to the API key

Returns the company linked to the API key. Any valid customer API key can read this resource.

Tags: Organization

cURL

curl https://idleatlas.com/api/customer/v1/organization \
  -H "x-api-key: ia_live_********************************"

Responses

200 Organization context.

{
  "organization": {
    "id": "org_123",
    "name": "Production integration",
    "slug": "acme-health",
    "status": "active"
  }
}

401 Invalid or missing API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

429 Too many customer API requests for the current API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

Credential Management

Manage customer API keys from a signed-in company admin session inside the app.

GET/api/customer/v1/api-keysSigned-in company admin session

List API keys for the active company

Returns the customer API keys for the caller's active company.

Tags: API Keys

Responses

200 Customer API keys.

{
  "apiKeys": [
    {
      "id": "org_123",
      "name": "Production integration",
      "start": "ia_live",
      "prefix": "ia_live",
      "enabled": true,
      "createdAt": "2026-03-23T00:00:00.000Z",
      "expiresAt": "2026-03-23T00:00:00.000Z",
      "lastRequestAt": "2026-03-23T00:00:00.000Z",
      "organizationId": "org_123",
      "revokedAt": "2026-03-23T00:00:00.000Z"
    }
  ]
}

403 Caller lacks permission to manage API keys.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

POST/api/customer/v1/api-keysSigned-in company admin session

Create an API key for the active company

Creates a new customer API key. The secret is returned once in the response and cannot be retrieved again later.

Tags: API Keys

Request body

{
  "name": "Production integration",
  "expiresInDays": 30
}

Responses

201 API key created.

{
  "apiKey": {
    "id": "org_123",
    "name": "Production integration",
    "start": "ia_live",
    "prefix": "ia_live",
    "enabled": true,
    "createdAt": "2026-03-23T00:00:00.000Z",
    "expiresAt": "2026-03-23T00:00:00.000Z",
    "lastRequestAt": "2026-03-23T00:00:00.000Z",
    "organizationId": "org_123",
    "revokedAt": "2026-03-23T00:00:00.000Z"
  },
  "secret": "ia_live_********************************"
}

400 Validation failed.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

403 Caller lacks permission to manage API keys.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

POST/api/customer/v1/api-keys/{apiKeyId}/revokeSigned-in company admin session

Revoke an API key

Disables a previously issued API key for the active company.

Tags: API Keys

Responses

200 API key revoked.

{
  "message": "API key revoked.",
  "apiKey": {
    "id": "org_123",
    "name": "Production integration",
    "start": "ia_live",
    "prefix": "ia_live",
    "enabled": true,
    "createdAt": "2026-03-23T00:00:00.000Z",
    "expiresAt": "2026-03-23T00:00:00.000Z",
    "lastRequestAt": "2026-03-23T00:00:00.000Z",
    "organizationId": "org_123",
    "revokedAt": "2026-03-23T00:00:00.000Z"
  }
}

403 Caller lacks permission to manage API keys.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

404 API key not found for the active company.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

Company Data

Read the company resources most integrations need after authentication succeeds.

GET/api/customer/v1/locationsAPI key header (x-api-key)

List locations for the current company

Returns the locations for the company linked to the API key. Any valid customer API key can read this resource.

Tags: Locations

cURL

curl https://idleatlas.com/api/customer/v1/locations \
  -H "x-api-key: ia_live_********************************"

Responses

200 Organization locations.

{
  "locations": [
    {
      "id": "org_123",
      "name": "Production integration",
      "code": "unauthorized",
      "status": "active",
      "displayLabel": "string"
    }
  ]
}

401 Invalid or missing API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

429 Too many customer API requests for the current API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

GET/api/customer/v1/membersAPI key header (x-api-key)

List people for the current company

Returns the people in the company and their role assignments. Any valid customer API key can read this resource.

Tags: Members

cURL

curl https://idleatlas.com/api/customer/v1/members \
  -H "x-api-key: ia_live_********************************"

Responses

200 Organization members.

{
  "members": [
    {
      "membershipId": "string",
      "userId": "string",
      "email": "string",
      "name": "Production integration",
      "status": "active",
      "joinedAt": "2026-03-23T00:00:00.000Z",
      "roles": [
        {
          "assignmentId": "string",
          "roleKey": "string",
          "scopeType": "string",
          "scopeId": "string",
          "scopeLabel": "string"
        }
      ]
    }
  ]
}

401 Invalid or missing API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

429 Too many customer API requests for the current API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

GET/api/customer/v1/invitationsAPI key header (x-api-key)

List invitations for the current company

Returns the invitations for the company linked to the API key. Any valid customer API key can read this resource.

Tags: Invitations

cURL

curl https://idleatlas.com/api/customer/v1/invitations \
  -H "x-api-key: ia_live_********************************"

Responses

200 Organization invitations.

{
  "invitations": [
    {
      "id": "org_123",
      "email": "string",
      "roleKey": "string",
      "scopeType": "string",
      "scopeId": "string",
      "scopeLabel": "string",
      "status": "active",
      "expiresAt": "2026-03-23T00:00:00.000Z",
      "createdAt": "2026-03-23T00:00:00.000Z"
    }
  ]
}

401 Invalid or missing API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

429 Too many customer API requests for the current API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

GET/api/customer/v1/rolesAPI key header (x-api-key)

List roles for the current company

Returns the role definitions for the company linked to the API key. Any valid customer API key can read this resource.

Tags: Roles

cURL

curl https://idleatlas.com/api/customer/v1/roles \
  -H "x-api-key: ia_live_********************************"

Responses

200 Organization role reference data.

{
  "roles": [
    {
      "key": "string",
      "label": "string",
      "description": "Display name for the key.",
      "scopeType": "string",
      "scopeLabel": "string",
      "isAssignable": true,
      "isProtected": true,
      "highlights": [
        "string"
      ],
      "permissions": [
        {
          "key": "string",
          "group": "string",
          "groupLabel": "string",
          "label": "string"
        }
      ]
    }
  ]
}

401 Invalid or missing API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}

429 Too many customer API requests for the current API key.

{
  "error": {
    "code": "unauthorized",
    "message": "API key revoked."
  }
}