Start a device authorization session.

POST

/device-authorize

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

• Production

Creates a short-lived device authorization for applicationAnchor. No client-auth JWT is required. Keep deviceCode private, show userCode to the user, and direct them to either verification URI. Poll /device-token no faster than the returned interval.

Request Body^required

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]+)*$/

Example^generated

{
  "applicationAnchor": "example"
}

Responses

200

Device authorization session created.

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]+)*$/

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}$/

userCode

required

Short human-facing code shown by the client and confirmed in the browser. Uses the Crockford-style alphabet without ambiguous letters.

string

/^[0-9ABCDEFGHJKMNPQRSTVWXYZ]{4}-[0-9ABCDEFGHJKMNPQRSTVWXYZ]{4}$/

verificationUri

required

Browser page where the user enters or confirms userCode.

string format: uri

verificationUriComplete

required

Browser URL pre-filled with userCode.

string format: uri

expiresIn

required

Session lifetime in seconds. Default production value is 600.

integer

>= 1

interval

required

Minimum polling interval in seconds. Default production value is 5.

integer

>= 1

Example^generated

{
  "applicationAnchor": "example",
  "deviceCode": "example",
  "userCode": "example",
  "verificationUri": "https://example.com",
  "verificationUriComplete": "https://example.com",
  "expiresIn": 1,
  "interval": 1
}

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

Malformed request body.

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

403

The application cannot start device authorization. The reason distinguishes:

• ApplicationNotActive - the application is unavailable.
• Layer3Denied - the application does not currently have an enabled DEVICE_CODE ReturnRule.

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

404

Application anchor not found.

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

429

Too many authorization requests. Retry later.

503

Device authorization is temporarily unavailable.

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