Device authorization

Use the Device Authorization Grant (RFC 8628) for TVs, CLIs, and other clients that cannot easily open a browser or accept keyboard input. The user approves the sign-in on another device, such as their phone, and your device never collects their Raha Account password.

1. Request device and user codes

POST to the discovered device_authorization_endpoint with form fields client_id, optional client_secret, and an optional space-separated scope. Client authentication follows your registered method. Resource indicators are not supported on this endpoint.

curl -X POST "$API_BASE/api/oauth2/device_authorization" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'scope=openid profile'

The response contains device_code, user_code, verification_uri, verification_uri_complete, expires_in, and the minimum polling interval in seconds.

2. Ask the user to approve

Show the user_code and verification_uri, or render verification_uri_complete as a QR code so the user can skip typing the code. The user opens the link, signs in to Raha Account if needed, and approves or denies the request on the hosted page.

Keep the device_code private; only the user_code is meant to be shown.

3. Poll the token endpoint

Poll no faster than the returned interval:

curl -X POST "$API_BASE/api/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'device_code=DEVICE_CODE'

While the user has not finished, the token endpoint returns an error and you keep polling. If you are asked to slow down, increase the interval. Stop polling when the request is approved, denied, or expired, or after expires_in has passed.

A successful response has the same shape as any other token response. Validate the ID token the same way as in the web app guide.