Authentication and API key scopes

Create workspace API keys, choose the read or write scope, send keys as bearer tokens and handle the errors that missing scopes and plans return.

Last updated October 21, 2026

On this page

Every API request carries a workspace API key as a bearer token:

HTTP

GET /v1/workspaces/wsp_8fK2nQ7xLm3Pz9Tb4Wv1/leads HTTP/1.1
Host: api.asdk.com
Authorization: Bearer asdk_live_…

A key belongs to one workspace and acts on that workspace only. Asking for a site, lead or conversation of another workspace answers 404 not-found, the same as an id that does not exist.

Create a key

Owners and admins create keys in the dashboard under Settings → API. Give each server or integration its own key, named after where it runs, so you can revoke one without touching the others. The full key (asdk_live_ and 43 letters or digits) is shown once; ASDK keeps only a fingerprint of it. A workspace can have 25 active keys.

Keep keys on your servers. Never put a key in a website, a mobile app or a repository: anyone with the key can read your workspace's leads and conversations.

Scopes

Scope	What the key can do
`read`	Every read endpoint: sites, sources, documents, Q&A pairs, conversations, leads and the CSV export, insights, knowledge gaps, search analytics, webhook endpoints and their delivery log.
`write`	Everything `read` can, plus: add Q&A pairs, sync a source now, change a lead's status, ask a site's agent a question (`POST /v1/sites/{siteId}/ask`) and manage webhook endpoints (add, change, remove, test, redeliver).

Every key reads; choose Read and write when you create it to add the write scope. Keys created before scopes existed are read-only. The API reference marks every endpoint that needs the write scope.

Some actions always need a person signed in to the dashboard, whatever the key's scope: managing members, API keys, sites and widget settings, and rotating a webhook secret.

Errors

Status and `type`	Meaning
`401 unauthorized`	No key, or the key is not valid or was revoked.
`403 insufficient-scope`	The endpoint needs the write scope and the key only reads.
`403 api-key-not-accepted`	The endpoint is for people signed in to the dashboard.
`403 not-in-plan`	The workspace's plan does not include the feature (API access or webhooks).
`403 coming-soon`	Server-side answers, knowledge search and the MCP server are part of API access, which is coming soon.
`404 not-found`	The resource does not exist or belongs to another workspace.
`429 rate-limited`	Too many requests; wait for the seconds in `Retry-After`.

JSON

{
  "type": "insufficient-scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "this endpoint needs an API key with the write scope"
}

Revoke a key

Revoke a key under Settings → API. It stops working immediately. To replace a key without downtime, create the new key, deploy it, then revoke the old one.