Authentication
Sessions for the web app, bearer tokens for clients, device sign-in for the CLI and mobile app, personal API tokens for scripts, and worker credentials.
| Client | How |
|---|---|
| Web | POST /auth/login with header x-client: web. The access token (15 minutes) comes in the body; the refresh token is an httpOnly SameSite=Strict cookie. POST /auth/refresh with x-client: web rotates it. |
| CLI, mobile, integrations | The refresh token is returned in the body. Send Authorization: Bearer <accessToken>. |
| CLI and mobile, any sign-in method | Device sign-in: POST /auth/device/start returns a code and a link; the person approves it in the web app; the client polls POST /auth/device/poll every intervalSec. Codes expire after 10 minutes and work once. |
| Scripts, CI, IDE extensions | A personal API token aot_…. Send Authorization: Bearer aot_…. |
| Workers | Device-code pairing issues a worker credential aow_…. |
Refresh tokens rotate on every use. Presenting an already-used token revokes the whole session family.
Personal API tokens
Create one under Settings → Your account → API tokens, or with POST /api/v1/me/tokens from a signed-in session.
The value is shown once; only a hash is stored.
- A token works only in its organization, with the role it was created with, capped at the owner's current role.
- It cannot use
/me/tokens, two-factor setup or/admin/*.
Terminal
export AO_SERVER=https://orchestration.example.com AO_ORG=org_… AO_TOKEN=aot_…
curl -H "Authorization: Bearer $AO_TOKEN" "$AO_SERVER/api/v1/orgs/$AO_ORG/tasks"Password sign-in
Terminal
curl -X POST "$AO_SERVER/api/v1/auth/login" -H "Content-Type: application/json" \
--data '{"email": "you@example.com", "password": "…"}'Accounts with two-factor authentication must also provide a code. Prefer API tokens for automation.