Look up a device authorization by its user code (RFC 8628 §3.3)

POST/v1/auth/device/verify

Resolves a user-entered user_code so the hosted UI can show WHAT is being authorized (the client and the requested scope) before the user decides. It makes no decision itself.

The user_code is a credential (§5.1): its entropy is low enough that the endpoint is only safe behind rate limiting, which x-rate-limit applies. A wrong or malformed code is answered identically to an expired one, so the endpoint cannot be used to probe which codes exist.

§5.1 also asks for an attempt budget, which the per-address request limit cannot provide: five wrong codes per signed-in user per code lifetime, keyed to the user so changing source address does not refill it. Spending it answers 429 with the problem code too_many_attempts — terminal, not a delay, and carrying no Retry-After: the flow is over and the person must start again at their device. A correct code presented after the budget is spent is not served either; the session it names is ended.

POST/v1/auth/device/verify

curl -X POST 'https://auth.example.com/v1/auth/device/verify' \
  -H "Content-Type: application/json" \
  -d '{
    "user_code": "WDJB-MJHT"
  }'

Response

200 OK

{
  "client_id": "tv-app",
  "client_name": "Living Room TV",
  "user_code": "WDJB-MJHT",
  "scope": "openid profile",
  "account_email": "alice@example.com",
  "expires_in": 900
}

Authorization

None. This endpoint does not take API credentials.

It reads the browser session from the Cookie header.

The request Cookie header; the interactive login / pending-auth session cookie, and the browser marker a sign-in is recognized by, are read from it.

Headers

Originstring
Browser Origin, checked (with Sec-Fetch-Site) as a same-origin/CSRF guard.
Sec-Fetch-Sitestring
Fetch metadata; only same-origin is trusted (CSRF guard).
Content-Typestring
Must be application/json — a JSON body cannot be a CORS simple request, closing form-based CSRF.
Cookiestring
The request Cookie header; the interactive login / pending-auth session cookie, and the browser marker a sign-in is recognized by, are read from it.

Request body

application/json

A user-entered device user code (RFC 8628 §3.3).

user_codestringrequired
The code shown on the device. Case and separators are normalized server-side, so "wdjb-mjht", "WDJB MJHT" and "WDJBMJHT" are the same code — §6.1 recommends exactly that leniency, since the user is transcribing from a screen.
Example"WDJB-MJHT"
1–32 characters

Responses

200 OKapplication/jsonThe pending device authorization, for display before the decision.
The pending device authorization, for display before the decision.
Headers
- Cache-Controlno-store
Body
What the device is asking for, so the user can decide.
- client_idstringrequired
  Example"tv-app"
- user_codestringrequired
  Example"WDJB-MJHT"
- client_namestring
  Example"Living Room TV"
- scopestring
  Example"openid profile"
- account_emailstring
  Example"alice@example.com"
- expires_ininteger · int64
  Seconds until the request expires.
  Example900
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/problem+jsonProblem details (RFC 9457).
Problem details (RFC 9457).
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"

PreviousRecord the user's consent decision NextApprove or deny a device authorization

Look up a device authorization by its user code (RFC 8628 §3.3)

POST/v1/auth/device/verify

Resolves a user-entered user_code so the hosted UI can show WHAT is being authorized (the client and the requested scope) before the user decides. It makes no decision itself.

Headers

Body

Body

Body

Headers

Body

Body

Body