/api/auth/device/approveAuthenticatedApprove a device sign-in request
The signed-in user approves the pending device authorization request (RFC 8628) their user code names: the client application is authorized for them, with the API scopes they approved (approved_api_scopes, among those the request asks for and the app may be granted), and the device's next poll of the token endpoint receives tokens for their account with the granted scope. Refused with 403 email_verification_required while the account's address is unverified and the deployment requires verification before a third-party hand-off. Unknown codes count towards the same limits as POST /api/auth/device/lookup.
post_api_auth_device_approveAuthenticationAuthentication & permissionsAuthenticated
Any authenticated user
- Accepted credentials
- Auth server session (refresh token cookie)
cookie "refresh_token_<auth_server_app_id>" - Access token (cookie)
cookie "access_token_<auth_server_app_id>" - Access token (Bearer)
Authorization: Bearer <JWT>
- Auth server session (refresh token cookie)
- Who may call
- Any authenticated user
Request body
Required — The user code and the API scopes approved.
| Property | Type | Description |
|---|---|---|
| user_code* | string | The user code shown on the device, as the user typed it: case-insensitive, dashes and spaces ignored. minLength: 1maxLength: 32 |
| approved_api_scopes | string[] | The API scopes the user left ticked. Recorded as the user's consent for those of them the request asks for and the app may be granted; the rest are not granted. Omitted or empty: no API scope is consented to now (OIDC scopes and API scopes consented to before are still granted). maxItems: 100 |
Responses
| Property | Type | Description |
|---|---|---|
| success* | true | |
| message* | string | |
| decision* | "approved" | "denied" | |
| client_app_id* | string | minLength: 2maxLength: 64pattern: ^[a-z0-9_-]*$ |
| scope | string | null | null | On approval: the granted scope (null for a plain OAuth 2.1 grant) |
Example request
curl -X POST 'https://auth.botreeinc.com/api/auth/device/approve' \
-b 'refresh_token_<auth_server_app_id>=<value>' \
-H 'Content-Type: application/json' \
-d '{
"user_code": "BCDF-GHJK",
"approved_api_scopes": [
"string"
]
}'