/api/auth/device/lookupAuthenticatedLook up a device sign-in request
The /device page's first step of the device authorization grant (RFC 8628): the signed-in user enters the user code their device shows, and gets back what the device asks for — the client application, the expiry, and the requested scopes in the consent screen's shape (consent) — so they can approve (POST /api/auth/device/approve) or deny (POST /api/auth/device/deny) it. Only pending, unexpired requests are found. Unknown codes are counted per account and per IP, and after a handful the endpoint answers 429 until the window passes (RFC 8628 §5.1 brute-force protection); codes that are found are never counted.
post_api_auth_device_lookupAuthenticationAuthentication & 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 to look up.
| 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 |
Responses
| Property | Type | Description |
|---|---|---|
| success* | true | |
| user_code* | string | The user code, formatted for display |
| client_app* | object | |
| app_id* | string | minLength: 2maxLength: 64pattern: ^[a-z0-9_-]*$ |
| app_name* | string | Typed in by the app's developers; not verified |
| app_description* | string | Typed in by the app's developers; not verified |
| created_at* | integer | When the device asked (Unix epoch ms) |
| expires_at* | integer | When the request expires (Unix epoch ms) |
| consent* | object | What the request asks for, as on the consent screen of a browser sign-in |
| success* | true | |
| authorized* | boolean | |
| consent_required* | boolean | |
| requested_oidc_scopes* | string[] | |
| api_server* | object | null | null | |
| api_server_id* | string | minLength: 2maxLength: 64pattern: ^[a-z0-9_-]*$ |
| api_server_name* | string | |
| granted_api_scopes* | object[] | |
| api_server_scope_id* | string (uuid) | |
| scope* | string | |
| description* | string | |
| pending_api_scopes* | object[] | |
| api_server_scope_id* | string (uuid) | |
| scope* | string | |
| description* | string |
Example request
curl -X POST 'https://auth.botreeinc.com/api/auth/device/lookup' \
-b 'refresh_token_<auth_server_app_id>=<value>' \
-H 'Content-Type: application/json' \
-d '{
"user_code": "BCDF-GHJK"
}'