/api/oidc/device_authorizationPublicDevice authorization endpoint
The OAuth 2.0 device authorization endpoint (RFC 8628 §3.1), advertised as device_authorization_endpoint: starts the device authorization grant for a device that cannot show the login page (a CLI, a TV app). The response's user_code and verification_uri are shown to the user, who enters the code on the auth server's /device page, signs in and approves (or denies) the request; meanwhile the device polls POST /api/oidc/token with grant_type=urn:ietf:params:oauth:grant-type:device_code and the device_code, every interval seconds, until it receives its tokens or access_denied / expired_token. Codes expire after 15 minutes. Only client applications whose managers enabled the grant (PUT /api/apps/{app_id}/device-authorization) may use it, never a dynamically registered client (unauthorized_client). Requests are rate limited per IP. Responses carry Cache-Control: no-store and Access-Control-Allow-Origin: * (no cookies are read).
post_api_oidc_device_authorizationOpenID Connect / OAuth 2.0Authentication & permissionsPublic
Anyone — no credentials required
- Accepted credentials
- None required
- Notes
- Client authentication as at the token endpoint (RFC 8628 §3.1): a confidential client (an app with a registered client secret) MUST authenticate with
client_secret_basicorclient_secret_post; a public client identifies itself withclient_idalone. The handler performs this itself.
Request body
Required — Form-encoded device authorization request.
| Property | Type | Description |
|---|---|---|
| client_id | string | The client application id. May be omitted when a confidential client authenticates with minLength: 2maxLength: 64pattern: ^[a-z0-9_-]*$ |
| client_secret | string |
|
| scope | string | OPTIONAL. Space-delimited scopes, as at the authorization endpoint: with |
| resource | string | OPTIONAL. RFC 8707 resource indicator naming the API server whose API scopes |
Responses
| Header | Type | Description |
|---|---|---|
| Cache-Control | string |
| Property | Type | Description |
|---|---|---|
| device_code* | string | The device verification code: poll the token endpoint with it ( |
| user_code* | string | The code the user enters on the verification page: 8 consonants in two groups of four. Entry is case-insensitive and ignores the dash. |
| verification_uri* | string | The auth server's |
| verification_uri_complete* | string | The |
| expires_in* | integer | Seconds until both codes expire. |
| interval* | integer | Seconds to wait between polls; add 5 on every |
Example request
curl -X POST 'https://auth.botreeinc.com/api/oidc/device_authorization' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=my-cli' \
--data-urlencode 'client_secret=string' \
--data-urlencode 'scope=openid email profile' \
--data-urlencode 'resource=https://api.example.com'