Connect with a device code

1. Register a public device client

Discover endpoints from OAuth metadata. Register once, then keep the returned client_id. Device clients use no secret or redirect URI. Send client_id in the request body; device clients do not use HTTP Basic authentication. Send response_types as an empty array or omit it. Additional unsupported registration metadata is ignored. Generic native-client callback URIs are accepted but discarded: registration returns redirect_uris: [] and never redirects a device client. Mixed browser/device grants are not supported. Existing browser clients continue using authorization code with PKCE.

curl 'https://staging.glidzr.com/api/auth/mcp/register' \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"My CLI","token_endpoint_auth_method":"none","grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"],"response_types":[],"scope":"openid offline_access"}'

2. Request and display a code

curl 'https://staging.glidzr.com/api/auth/device/code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'scope=openid offline_access' \
  --data-urlencode 'resource=https://staging.glidzr.com'

Authorization and token endpoints accept application/x-www-form-urlencoded (as shown) or JSON. Use the resource value from protected-resource metadata: https://staging.glidzr.com. It is optional for existing clients. This deployment supports one resource; a different URL returns invalid_target. Unsupported authorization and polling extension parameters are ignored.

Display user_code and verification_uri from the response. You may also open verification_uri_complete, but the person must still confirm the code and approve. Keep device_code private. Codes expire after 600 seconds.

3. Poll for the token

curl 'https://staging.glidzr.com/api/auth/mcp/token' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'device_code=YOUR_DEVICE_CODE' \
  --data-urlencode 'resource=https://staging.glidzr.com'

Wait at least the returned interval (initially 5 seconds) between requests. authorization_pending means keep waiting. On slow_down, permanently add 5 seconds to your interval. Also honor HTTP 429 Retry-After. Stop on access_denied, expired_token or invalid_grant; request a new code if needed.

Success returns access_token, token_type, expires_in and scope. Access lasts one hour. offline_access also returns a refresh_token, valid for seven days. Refresh through the same token endpoint using grant_type=refresh_token, client_id and refresh_token, with the same optional resource. Save the replacement token pair atomically: refresh consumes the previous pair. A device code is redeemable only once.

Access and revocation

Supported scopes are openid, profile, email and offline_access; request only those registered for your client. These tokens permit existing agent ledger reads, pending proposals and explicitly confirmed structured entries. They never create browser sessions or authorize project assignment or recurring instructions.

Manage device connections at Connect a device, also linked from Settings. Revoking a connection removes that account's access and refresh tokens and approved device requests for the selected client. Google account recovery also revokes old access. Connect again afterward.

Code creation and device registration share a limit of 10 requests per IP per minute; browser review and management share 20, and polling allows 60. The shared ingress limit also applies. All auth request bodies are capped at 64 KiB. Responses containing codes or tokens must not be cached or logged.