POST/api/auth/device/lookupAuthenticated

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

operationId post_api_auth_device_lookupAuthentication

Authentication & permissionsAuthenticated

Any authenticated user

Accepted credentials
Who may call
Any authenticated user

Request body

Required — The user code to look up.

application/json
DeviceUserCodeRequest
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

JSONExample
"user_code""BCDF-GHJK"

Responses

application/json
DeviceAuthorizationDescription
PropertyTypeDescription
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
JSONExample
"success"true
"user_code""BCDF-GHJK"
"client_app"
"app_id""string"
"app_name""string"
"app_description""string"
"created_at"1
"expires_at"1
"consent"
"success"true
"authorized"true
"consent_required"true
"requested_oidc_scopes"
"string"
"api_server"
"api_server_id""string"
"api_server_name""string"
"granted_api_scopes"
"pending_api_scopes"

Example request

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