Poll and consume a device authorization session.

POST

/device-token

curl --request POST \
  --url https://device-api.sudomimus.com/device-token \
  --header 'Content-Type: application/json' \
  --data '{ "deviceCode": "example" }'

• Production

Polls the authorization identified by deviceCode. Polling states use OAuth-style device-flow errors. Success consumes the authorization and returns an access/refresh token pair; the code cannot issue tokens again.

Request Body^required

Media typeapplication/json

object

deviceCode

required

High-entropy bearer secret for /device-token, returned only to the initiating client. Keep it private; do not display it to the browser user.

string

/^dvc_[0-9a-f]{64}$/

Example^generated

{
  "deviceCode": "example"
}

Responses

200

Tokens issued and the device authorization session consumed.

Media typeapplication/json

object

applicationAnchor

required

Public anchor identifying the application. Strict kebab-case, unique at application creation, and immutable after creation.

string

>= 3 characters <= 64 characters /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/

accessToken

required

Short-lived access token (JWT). Payload sub is the pairwise sector subject, sid identifies the session, and jti identifies this access-token instance. It contains no profile claims or raw account identifier; use Session API /userinfo for current shared identity data.

string

refreshToken

required

Long-lived refresh token (JWT). Payload sid binds the session, jti names this exact bearer version, and rotationVersion is a positive integer. It contains no user identifier. Use Session API /refresh to rotate it and issue later access tokens.

string

claims

required

Per-claim view across the five shareable claims - why a claim is or is not present in the minted token.

object

email

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits a generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder when the user has not shared real data.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

firstName

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits a generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder when the user has not shared real data.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

lastName

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits a generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder when the user has not shared real data.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

staticAvatar

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits a generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder when the user has not shared real data.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

animatedAvatar

required

One shareable claim: what the application requests (requirement) joined with the user’s standing decision (state). UNKNOWN means the user was never asked; DENIED means the user explicitly declined.

object

requirement

required

The developer’s policy for the claim. SYNTHETIC_ONLY always emits a generated placeholder and never asks for real data. SYNTHETIC_FALLBACK guarantees the claim is present but uses a generated placeholder when the user has not shared real data.

string

Allowed values: SYNTHETIC_ONLY OFF OPTIONAL REQUIRED SYNTHETIC_FALLBACK

state

required

string

Allowed values: UNKNOWN GRANTED DENIED

Example

{
  "claims": {
    "email": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    },
    "firstName": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    },
    "lastName": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    },
    "staticAvatar": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    },
    "animatedAvatar": {
      "requirement": "SYNTHETIC_ONLY",
      "state": "UNKNOWN"
    }
  }
}

Headers

Cache-Control

string

Allowed values: no-store

Prevent storage of the token or polling response.

Pragma

string

Allowed values: no-cache

Legacy cache instruction retained for token polling responses.

400

Device-flow polling state or terminal client-visible refusal:

• authorization_pending - the user has not approved or denied the request yet. Continue polling after the current interval.
• slow_down - the client is polling too quickly. Use the returned interval value for subsequent polls.
• access_denied - the user or current policy denied issuance.
• expired_token - the device authorization session expired.
• invalid_request - the request body is missing, malformed, or structurally invalid; or the deviceCode is unknown or has already been consumed.

Media typeapplication/json

OAuth-style device-flow error body returned by /device-token. Polling clients should branch on error, not on Sudomimus wire reason symbols.

object

error

required

string

Allowed values: authorization_pending slow_down access_denied expired_token invalid_request server_error

interval

Present for slow_down; use this value for subsequent polls.

integer

>= 1

Example

{
  "error": "authorization_pending"
}

Headers

Cache-Control

string

Allowed values: no-store

Prevent storage of the token or polling response.

Pragma

string

Allowed values: no-cache

Legacy cache instruction retained for token polling responses.

500

Token issuance failed. Stop polling and start a new device authorization if the user wants to retry.

Media typeapplication/json

OAuth-style device-flow error body returned by /device-token. Polling clients should branch on error, not on Sudomimus wire reason symbols.

object

error

required

string

Allowed values: authorization_pending slow_down access_denied expired_token invalid_request server_error

interval

Present for slow_down; use this value for subsequent polls.

integer

>= 1

Example

{
  "error": "authorization_pending"
}

Headers

Cache-Control

string

Allowed values: no-store

Prevent storage of the token or polling response.

Pragma

string

Allowed values: no-cache

Legacy cache instruction retained for token polling responses.

default

Error response.

Media typeapplication/json

Error response body for failures outside the device polling state machine. /device-token polling states use DeviceTokenError. Invalid JSON request bodies return InvalidBody.

object

reason

Stable machine-readable reason code.

string

Example^generated

{
  "reason": "example"
}