POST/api/oidc/device_authorizationPublic

Device 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).

operationId post_api_oidc_device_authorizationOpenID Connect / OAuth 2.0

Authentication & 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_basic or client_secret_post; a public client identifies itself with client_id alone. The handler performs this itself.

Request body

Required — Form-encoded device authorization request.

application/x-www-form-urlencoded
OidcDeviceAuthorizationRequest
PropertyTypeDescription
client_idstring

The client application id. May be omitted when a confidential client authenticates with client_secret_basic (the id then comes from the Authorization header).

minLength: 2maxLength: 64pattern: ^[a-z0-9_-]*$

client_secretstring

client_secret_post authentication, for confidential clients.

scopestring

OPTIONAL. Space-delimited scopes, as at the authorization endpoint: with openid the device also receives an id_token; API scopes of the API server named by resource may be asked for. Unknown scopes are ignored. What is granted is decided when the user approves the request.

resourcestring

OPTIONAL. RFC 8707 resource indicator naming the API server whose API scopes scope asks for (an API server id or the URL of one of its registered domains). At most one.

Responses

HeaderTypeDescription
Cache-Controlstring
application/json
OidcDeviceAuthorizationResponse
PropertyTypeDescription
device_code*string

The device verification code: poll the token endpoint with it (grant_type=urn:ietf:params:oauth:grant-type:device_code). Never show it to the user.

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 /device page, where the user enters the code. Show it with the user code.

verification_uri_complete*string

The /device page with the code filled in, for a link or QR code. Still show the user code so the user can compare it with the page.

expires_in*integer

Seconds until both codes expire.

interval*integer

Seconds to wait between polls; add 5 on every slow_down.

JSONExample
"device_code""string"
"user_code""BCDF-GHJK"
"verification_uri""https://auth.example.com/device"
"verification_uri_complete""https://auth.example.com/device?user_code=BCDF-GHJK"
"expires_in"900
"interval"5

Example request

bashcurl
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'