Authentication

Asiri authenticates every API request with a bearer token in the Authorization header:

Authorization: Bearer asiri_live_<random>

There is no separate key id / secret handshake for external integrations. The entire token is the credential. Treat it like a password.

First-party dashboard clients may also use the Better Auth session cookie, but external integrations should use tenant API keys.

Trust model

• Workspace-scoped. A key only ever sees data from the workspace that minted it. Cross-tenant access is enforced at the database layer via row-level security — see Concepts → RLS.
• Scope-gated. Each key carries explicit external API scopes such as reports:read, audit:read, or webhooks:write. Requests outside the public allowlist or granted scopes fail with 403 forbidden. See API Keys.
• Auditable. Every authenticated call is logged with the key id, scope, route, and request id. See Concepts → Audit log.

Environments

Test keys are sandboxed: they cannot read or write production data, and webhooks fire to your configured staging URL only.

Key rotation

Rotate keys on a schedule (we recommend every 90 days) and immediately on any suspected leak. The dashboard supports overlap windows: mint the new key, redeploy, then revoke the old one.

Errors

Error bodies use the canonical envelope:

{
  "error": {
    "code": "rbac_denied",
    "message": "API key external API scopes do not permit: reports:read",
    "requestId": "01K..."
  }
}