Authentication

Sign in with the CLI

atrium login

Follow the displayed verification link, sign in, and approve the device request in the intended workspace. Only approve codes for a login you initiated. The CLI stores credentials locally for subsequent authenticated commands. Use atrium logout when finished on a shared machine.

The API base is https://api.atrium.st/v0. Browser approval opens on auth.atrium.st. Do not send token-exchange requests to the browser sign-in domain.

Implement device authorization

Custom developer clients can start the device flow with form data or JSON:

POST /v0/oauth/device/code
Content-Type: application/x-www-form-urlencoded

client_id=atrium-cli

Use the response's verification_uri or verification_uri_complete, user_code, device_code, expires_in, and interval. Display the verification instructions and poll the token endpoint at the returned interval:

POST /v0/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=<device-code>&client_id=atrium-cli

Treat authorization_pending as a wait state, honor slow_down, and stop polling on rejection or expiry. Start a new device flow after expiry. Never put the device code in analytics or logs.

Use and refresh access tokens

A successful token response includes access and refresh tokens, token_type, expires_in, expires_at, and user/workspace context. Treat tokens as opaque credentials rather than depending on their internal claims.

GET /v0/platform/me
Authorization: Bearer <access-token>

Refresh before expiry or after an authentication failure:

POST /v0/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh-token>&client_id=atrium-cli

Replace stored credentials with those returned by a successful refresh. Keep tokens in a protected credential store; never commit them, embed them in frontend code, or include them in support reports. Do not retry failed writes blindly after reauthentication; preserve their idempotency keys.

Select a workspace

Use GET /v0/platform/workspaces, then POST /v0/platform/workspaces/<workspace-id>/select with the current bearer token. For CLI authentication, selection returns a fresh access token for the chosen workspace.

Use the replacement token immediately. Browser workspace selection and an already-issued CLI access token can have different contexts. See Workspaces and team access.

A valid token does not grant access to another workspace's developer resources. A permission error should trigger a workspace and membership check, not repeated login attempts.

Revoke credentials

atrium logout handles CLI sign-out. Custom clients can revoke a refresh token:

POST /v0/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<refresh-token>&client_id=atrium-cli

Remove locally stored credentials after sign-out. Use a new device authorization flow if refresh is rejected or the workspace grant is no longer available.