Device authorization

Use device authorization for TVs, CLIs, and other input-constrained clients. The device never collects the user's Raha Account password.

1. Request device and user codes

POST {API_BASE}/api/oauth2/device_authorization using form fields client_id, optional client_secret, and optional space-separated scope. Client authentication follows the registered method. Resource indicators are not currently 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.

2. Ask the user to approve

Show the user code and verification URI, or display the complete URI as a QR code. The browser validates the code at GET /api/v1/authentication/device-requests/{user_code}. An authenticated account/profile approves or denies it with POST /api/v1/authentication/device-requests/{user_code}/decisions.

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'

Stop polling when the request is approved, denied, expired, or exchanged.