Device authorization

Sigma enables Better Auth's device authorization plugin. A device requests a code, a person approves it in a browser at Device approval, and the device polls for completion. This is distinct from an Agent Auth capability grant.

Request a code

POST /api/auth/device/code accepts JSON:

{ "client_id": "your-registered-client-id", "scope": "openid profile" }

The response contains device_code, user_code, verification_uri, verification_uri_complete, expires_in, and interval. Display the user code and trusted verification URI. Keep the device code private; it is the polling credential.

The audited configuration uses a 15-minute expiry and five-second polling interval. Always honor the returned values rather than hardcoding them.

Poll

POST /api/auth/device/token accepts:

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "returned-device-code",
  "client_id": "your-registered-client-id"
}

Wait at least the returned interval between polls. Continue on authorization_pending, increase the delay on slow_down, honor HTTP 429 retry timing, and stop on expired_token or access_denied.

The deployed Better Auth schema describes the success response as session and user. Do not assume this endpoint returns the same access_token/id_token bundle as /api/auth/oauth2/token. Use the installed client's session contract and protect any returned session credential.

Human approval

The person signs in, reviews the requesting app/code and requested scope, and approves or denies. GET /api/device/request?user_code=… is a session-protected metadata helper for that UI; it is not the device's token endpoint.

Never instruct someone to approve an unsolicited code. Device approval authorizes the account flow; it does not export a private key or decrypt a backup on the remote device. See agents for capability-based automation and rate limits for polling limits.