Skip to main content

Authentication

Every route in this section (except GET /health) requires an API key sent as a bearer token:

Authorization: Bearer <API_KEY>

Getting a key​

API keys are issued from the dashboard, shown once at creation. Store the value as soon as it's shown — there's no way to view it again later, only to revoke it and issue a new one.

A key looks like ak_xxxxxxxxxxxx....

Key scopes​

Every key is minted with a scope, chosen when you create it in the dashboard:

ScopeBound toDrives
sdk (default)A single projectThe mobile agent surface (/agent/* — sessions, messages, actions). This is the key your app embeds.
operatorThe whole workspace (no project)The escalation operator surface (/escalations/*). Lets your OWN systems — a helpdesk bridge, a Slack bot, an internal support panel — act as a human operator instead of only the Appilots dashboard. See Operator API.

The two scopes are mutually exclusive by design: an operator key is rejected by every /agent/* route, and an sdk key is rejected by every /escalations/* route, even though both are ak_... bearer tokens sent the same way. Never share a key across the two use cases — mint a separate key per integration.

Example​

curl https://api.appilots.com/api/v1/agent/session \
  -X POST \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..." \
  -H "Content-Type: application/json" \
  -d '{}'
const res = await fetch("https://api.appilots.com/api/v1/agent/session", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_xxxxxxxxxxxx...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

401 responses​

A request with a missing or malformed Authorization header (anything that doesn't start with Bearer ak_), an invalid key, or an expired key returns 401 with the standard error envelope. Treat any 401 as a signal to check the key rather than retry the request as-is — see Errors for the full error code reference.

Keeping keys safe​

Never embed an API key in client-side code that ships to end users (e.g. a mobile app bundle) — it's a project-scoped credential meant for your own server or tooling. See Security best practices for more on this.

Last updated on