Skip to main content

​
API keys

Authenticate every request with a Bearer token:
Keys are environment-prefixed: The full secret is shown once at creation. Only a prefix (ask_live_…) and the last 4 characters are stored for display; the key itself is stored as a SHA-256 hash.
Treat keys like passwords. If a key leaks, rotate it from Settings → API Keys — rotation issues a new secret and invalidates the old one immediately.

​
Scopes

Each key carries resource:action scopes (e.g. assistants:read, calls:create). A request to an endpoint you lack the scope for returns 403. Role presets:
  • read_only → read + list on every resource
  • read_write → full CRUD + list
  • admin → all scopes
  • custom → exactly the scopes you assign

​
Selecting a subaccount

A key may be authorized for one or more subaccounts. Tell the API which one a request targets, in priority order:
  1. X-Subaccount-Id header (recommended)
  2. subaccount_id in the request body
  3. location_id in the request body (legacy alias)
A single-subaccount key defaults to its one subaccount. Requesting a subaccount the key isn’t authorized for returns 403.

​
IP allowlisting

A key can be restricted to specific source IPs or CIDR ranges. Requests from other addresses are rejected with 401.