Developer docs: Authentication

Authentication

Every request carries an API key in the X-API-Key header. Keys belong to your organization, carry explicit scopes and can be limited to one agent.

Create a key

Sign in as an owner or admin and open Settings → API keys.
Choose Create key, give it the name of the system that will use it (for example “CRM sync”), and pick its scopes.
Optionally bind it to one agent and set an expiry date.
Copy the key. It starts with bck_ and is shown only once; we store only a hash of it. If you lose it, revoke it and create a new one.

Request header (example key)

X-API-Key: bck_0000000000000000000000000000000000000000000000000

Check a key with the account endpoint, which every key may call:

cURL

curl "https://bookifycall.com/api/v1/external/me" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

It returns your organization, plan, the key's scopes and your rate limit (reference).

When authentication fails

Status	Code	Meaning
401	`APIKEY_002`	Header missing, or the key is unknown, expired or revoked.
403	`APIKEY_003`	The key lacks a scope this endpoint needs. `error.details.required` and `error.details.granted` say which.
403	`PLAN_001`	Your plan does not include API access (Enterprise).
403	`AUTH_006`	An agent-bound key asked for another agent, or for an organization-wide resource.

Example error · 403

{
  "success": false,
  "message": "API key is missing a required scope",
  "error": {
    "code": "APIKEY_003",
    "message": "API key is missing a required scope",
    "details": {
      "required": [
        "recordings:read"
      ],
      "granted": [
        "calls:read"
      ]
    }
  },
  "meta": {
    "timestamp": "2026-10-16T12:00:00.000Z",
    "path": "/api/v1/external/calls-history/…/recording"
  }
}

Scopes

A key can do only what its scopes allow. A key created without choosing scopes is read-only: calls:read, leads:read, appointments:read, agents:read, numbers:read, webhooks:read, compliance:read. Write scopes never include their read counterpart, and recordings:read is separate from calls:read because audio is more sensitive than metadata.

Scope	Endpoints
`calls:read`	GET /usage GET /analytics/summary GET /insights/summary GET /calls-history GET /calls-history/{id} GET /calls-history/{id}/transcript GET /scheduled-calls GET /scheduled-calls/{id}
`recordings:read`	GET /calls-history/{id}/recording
`calls:write`	POST /calls/outbound
`scheduled_calls:write`	POST /scheduled-calls DELETE /scheduled-calls/{id}
`leads:read`	GET /leads GET /leads/{id}
`appointments:read`	GET /appointments GET /appointments/{id}
`agents:read`	GET /agents GET /agents/{id}
`agents:write`	POST /agents PATCH /agents/{id} DELETE /agents/{id} PATCH /agents/{id}/knowledge-base PATCH /agents/{id}/custom-apis PATCH /agents/{id}/transfer-contacts
`numbers:read`	GET /numbers
`numbers:write`	POST /numbers/{id}/assign PATCH /numbers/{id}/fallback
`compliance:read`	GET /compliance/a2p GET /compliance/porting
`webhooks:read`	GET /webhooks
`webhooks:write`	POST /webhooks DELETE /webhooks PATCH /webhooks/{id} POST /webhooks/{id}/rotate-secret POST /webhooks/replay

Agent-bound keys

Bind a key to one agent when a system should only ever see that agent, for example one location:

Reads return only that agent's calls, recordings, leads from its calls, appointments, scheduled calls and numbers. Records with no agent (leads you entered by hand) stay visible.
Another agent's record answers 404, exactly like a record that does not exist.
Outbound calls use the bound agent by default. Webhook subscriptions, compliance status and creating agents are organization-wide, so a bound key gets 403 AUTH_006 there.

Rotate a key

Create a new key with the same scopes.
Deploy it to your system and confirm requests succeed (GET /me).
Revoke the old key in Settings → API keys. Revocation applies to the very next request.

Keys can carry an expiry date (up to five years ahead); an expired key answers 401 APIKEY_002. Settings shows when each key was last used and flags keys whose creator has left the team.

NextPagination, errors and limits