Skip to content
Sudomimus

Start a device authorization session.

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

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

Section titled “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

Section titled “ Responses ”

200

Section titled “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

Section titled “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

Section titled “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

Section titled “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

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