POST/api/auth/device/approveAuthenticated

Approve 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.

operationId post_api_auth_device_approveAuthentication

Authentication & permissionsAuthenticated

Any authenticated user

Accepted credentials
Who may call
Any authenticated user

Request body

Required — The user code and the API scopes approved.

application/json
ApproveDeviceAuthorizationRequest
PropertyTypeDescription
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_scopesstring[]

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

JSONExample
"user_code""BCDF-GHJK"
"approved_api_scopes"
"string"

Responses

application/json
DeviceAuthorizationDecisionResponse
PropertyTypeDescription
success*true
message*string
decision*"approved" | "denied"
client_app_id*string

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

scopestring | null | null

On approval: the granted scope (null for a plain OAuth 2.1 grant)

JSONExample
"success"true
"message""string"
"decision""approved"
"client_app_id""string"
"scope""string"

Example request

bashcurl
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"
  ]
}'