Authenticate API requests

Send your personal API token as a bearer header on every request. There is no public endpoint and no anonymous mode. Send the token in the Authorization header only. A token in a query string is ignored, answers 401, and is never repeated in the error body.

curl -H "Authorization: Bearer asob_…" \
  https://your-host/api/backend/health

const response = await fetch("https://your-host/api/backend/health", {
  headers: { Authorization: `Bearer ${process.env.ASOBEAST_API_TOKEN}` },
});
const health = await response.json();

import os, requests

response = requests.get(
    "https://your-host/api/backend/health",
    headers={"Authorization": f"Bearer {os.environ['ASOBEAST_API_TOKEN']}"},
)
health = response.json()

Two credential types

Credential	Used by	Obtained from
Session cookie	The dashboard in a browser	Signing in. The proxy forwards it for you
Personal API token	Scripts, the MCP server, continuous integration	The API tokens card in Integrations

Both carry the same entitlement checks. A token can be narrower than a session: it carries a scope and an optional expiry, and a read only token is refused with 403 the moment it tries to change anything. Give each consumer its own token and revoke individually. A token cannot create or revoke tokens, change the password, schedule workspace deletion or manage the team; those routes need a session. See Personal API tokens.

Scope and expiry

Setting	Values	Default
Scope	`read` or `write`	`read`
Expiry	Up to 365 days, or never	Never

Read only is the right default for anything agentic. The MCP server lists the tools that change things only to a token with the write scope, so give an agent a read token unless it has to change something. An expired token fails authentication with 401 exactly like a revoked one. Called with a token, GET /auth/me also reports the token’s scope as tokenScope. A browser session has no scope, so the field is absent. Rate limits count per workspace rather than per token, so minting a second token buys no extra capacity. See Rate limits and quotas.

Status codes you will see

Status	Meaning
`401`	The credential is missing, malformed, revoked or signed with a rotated secret
`402`	The account is not entitled, which only happens when `BILLING_ENABLED` is `true`
`403`	The token is read only and the request would change something, the route needs a signed in session and not a token, or the workspace is suspended
`429`	A plan rate limit is spent. `Retry-After` says when it reopens
`404` on `/docs` or `/admin/queues`	You are not the platform operator. These surfaces answer `404` rather than confirming they exist

A 401 after a deployment usually means AUTH_SECRET was rotated, which invalidates sessions. Personal API tokens survive a rotation, because they are stored as hashes rather than signed. See Rotate secrets.

Keep the token out of your history

Read it from an environment variable rather than typing it into a shell.

export ASOBEAST_API_TOKEN=asob_…
curl -H "Authorization: Bearer $ASOBEAST_API_TOKEN" \
  https://your-host/api/backend/apps

Error responses

The envelope every failure returns.

Authentication and accounts

Sessions, guards and entitlements.

Overview

Endpoints

Authenticate API requests

Two credential types

Scope and expiry

Status codes you will see

Keep the token out of your history

Error responses

Authentication and accounts

​Two credential types

​Scope and expiry

​Status codes you will see

​Keep the token out of your history

​Related

Error responses

Authentication and accounts

Two credential types

Scope and expiry

Status codes you will see

Keep the token out of your history

Related