CLI auth

Endpoint split

OAuth implementation lives on the versioned API. The browser-facing activation surface lives on the auth app.

Production CLI defaults should use the API domain:

POST https://api.atrium.st/v0/oauth/device/code
POST https://api.atrium.st/v0/oauth/token
POST https://api.atrium.st/v0/oauth/revoke

Root API routes exist only as compatibility aliases for old clients.

Device-code request

POST /v0/oauth/device/code accepts form or JSON:

client_id=atrium-cli
scope=...

The response includes a user code, a device code, polling interval details, and activation URLs. The verification URL should point at the auth app:

https://auth.atrium.st/activate?user_code=XXXX-XXXX

The API-hosted verify page was removed. GET /v0/oauth/device/verify now redirects to the auth app activation page.

Browser approval

The auth app exposes:

GET /activate
GET /activate/{code}
GET /oauth/device/verify

The approval request carries the signed-in browser user's Supabase bearer token to POST https://api.atrium.st/v0/oauth/device/authorize. Approval is scoped to that user's current Atrium workspace.

Token exchange

POST /v0/oauth/token supports:

grant_type=urn:ietf:params:oauth:grant-type:device_code
grant_type=refresh_token

Token responses include:

{
  "access_token": "eyJ...",
  "refresh_token": "rt_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-08-30T00:00:00Z",
  "scope": "...",
  "user": {},
  "workspace": {},
  "api_base_url": "https://api.atrium.st/v0"
}

CLI access tokens are Atrium-scoped JWTs with issuer atrium-api, audience atrium-cli, token_use=access, user subject, workspace identifiers, client id, scope, and refresh-token id.

Workspace selection

Control-plane workspace auth accepts these CLI bearer tokens anywhere workspace auth is required. Selecting a workspace updates the stored refresh token workspace and returns a fresh access token.

GET  /v0/platform/workspaces
POST /v0/platform/workspaces/{workspace_id}/select

Sandbox endpoints

During sandbox testing, use:

https://api.peter.sandbox.atrium.st/v0/oauth/device/code
https://api.peter.sandbox.atrium.st/v0/oauth/token
https://auth.peter.sandbox.atrium.st/activate?user_code=XXXX-XXXX
https://api.peter.sandbox.atrium.st/v0/platform

Strip trailing slashes before appending /oauth/... to the versioned API base or /platform/... to the versioned API base in clients.