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 session for the application identified by applicationAnchor.

No client-auth JWT is required or accepted here. The application must already have an enabled Layer 3 DEVICE_CODE ReturnRule. The caller keeps deviceCode private and polls /device-token; the user sees userCode and approves the request at verificationUri or verificationUriComplete.

The client should wait at least interval seconds between /device-token polls. Polling faster can return slow_down with a larger interval.

Request Body ^required

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

Example ^generated

{
  "applicationAnchor": "example"
}

Responses

200

Device authorization session created.

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

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
}

400

Malformed request body.

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

403

The application cannot start device authorization. The reason distinguishes:

• ApplicationDisabled - the application has been disabled.
• Layer3Denied - the application does not currently have an enabled DEVICE_CODE ReturnRule.

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

404

Application anchor not found.

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

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