Skip to content
Sudomimus

Poll and consume a device authorization session.

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

Polls the session identified by deviceCode. Pending and terminal refusal states are serialized as OAuth-style device-flow errors, not Sudomimus { "reason": "..." } wire reasons.

A successful response consumes the device authorization session and returns a normal Sudomimus application access/refresh token pair. Repeating the same request after success cannot mint another pair.

Request Body required

Section titled “Request Body required ”
Media type application/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

Section titled “ Responses ”

200

Section titled “200 ”

Tokens issued and the device authorization session consumed.

Media type application/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). The application-visible user key is the subject (sector subject) claim. Claim fields such as emailAddress, firstName, and lastName are minted according to the application’s claim policy and the user’s standing grant.

string
refreshToken
required

Long-lived refresh token (JWT). Use Connect /refresh to rotate it and issue later access tokens.

string
claims
required

Per-claim view across the three 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 guarantees the claim is present but permits a generated placeholder when the user has not shared real data.

string
Allowed values: OFF OPTIONAL REQUIRED SYNTHETIC
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 guarantees the claim is present but permits a generated placeholder when the user has not shared real data.

string
Allowed values: OFF OPTIONAL REQUIRED SYNTHETIC
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 guarantees the claim is present but permits a generated placeholder when the user has not shared real data.

string
Allowed values: OFF OPTIONAL REQUIRED SYNTHETIC
state
required
string
Allowed values: UNKNOWN GRANTED DENIED
Example 
{
  "claims": {
    "email": {
      "requirement": "OFF",
      "state": "UNKNOWN"
    },
    "firstName": {
      "requirement": "OFF",
      "state": "UNKNOWN"
    },
    "lastName": {
      "requirement": "OFF",
      "state": "UNKNOWN"
    }
  }
}

400

Section titled “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 denied the request, approval failed, or policy no longer allows token issuance.
  • expired_token - the device authorization session expired.
  • invalid_request - the deviceCode is unknown or has already been consumed.
Media type application/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"
}

500

Section titled “500 ”

Token issuance failed after approval. The device authorization session is failed server-side and the client should stop polling.

Media type application/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"
}

default

Section titled “default ”

Error response.

Media type application/json

Error response body for non-polling validation and infrastructure failures. /device-token handler-level polling states use DeviceTokenError instead.

object
reason

Stable machine-readable reason code.

string
Example generated
{
  "reason": "example"
}