Authentication

Send the key as a bearer token on every request: Authorization: Bearer pxl_…. Keys start with pxl_.

• Make a key in Pixl under Connections › Developers, with Create a key. It works in that workspace only.
• The key is shown once, when you make it. Pixl can't show it again; make a new one if it's lost.
• A key can never do more than the person who made it. Each request also checks that person's role in the workspace.
• If that person leaves the workspace, their keys stop working there.
• Revoke a key from its card (⋯ › Revoke). It stops at once.

A request with a missing, wrong, revoked or expired key gets a 401:

{
  "detail": "Invalid or expired API key"
}

A scope is a section of the API and an action: voice:write, contacts:read. Reading means GET; every other method is writing. A write scope includes read, so you never need to pick both.

• A new key starts with chat:write only: it can send messages to your agents and nothing else. Add what it needs.
• Full access (*) is its own choice. It reaches everything the person who made it can, including what no scope covers.
• Keys made before 25 October 2026 with no scopes keep full access.

A request the key's scopes don't cover gets a 403 that names the scope it needs:

{
  "detail": {
    "code": "api_key_scope_denied",
    "message": "This API key does not carry the 'voice:write' scope. Create a key with that scope, or use a key with no scopes for unrestricted access.",
    "required_scope": "voice:write",
    "required_scopes": [
      "voice:write"
    ]
  }
}

Each endpoint in these docs shows the scope it needs beside its path.

Pick only what the integration does. For a system that starts calls and WhatsApp messages and reads the results:

A key made under Connections › Developers is pinned to that workspace. A request that asks for another workspace, in the X-Workspace-ID header or in the path, query or body, is refused:

{
  "detail": {
    "code": "api_key_workspace_mismatch",
    "message": "This API key is scoped to a different workspace than this request asks for. Use a key minted for that workspace, or drop the workspace from the request."
  }
}

Keys for every workspace

Settings › Account can make a key that works in every workspace you belong to. Such a key acts in the workspace named by the X-Workspace-ID header, and in your primary workspace when there is none. We recommend one pinned key per workspace instead: a mistake can then only reach one workspace.

To find your workspaces' ids:

GET/teamsScope: workspace:read

curl "https://api.pixlagents.com/api/v1/teams" \
  -H "Authorization: Bearer $PIXL_API_KEY"

[
  {
    "id": "workspace_123",
    "name": "Sample Clinic",
    "is_active": true,
    "created_at": "2026-09-01T10:00:00"
  }
]

• Call the API from your server only. Never put a key in a website, an app, a spreadsheet or a message.
• Keep it in your secret store or an environment variable, not in your code.
• Use one key per integration, with only the scopes it needs. Then you can revoke one without stopping the others.
• To change a key: make the new one, switch your system to it, then revoke the old one.
• If a key may have leaked, revoke it straight away and make a new one.