v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Initiate a device authorization request

Starts the OAuth 2.0 Device Authorization flow for a device that cannot perform browser-based redirects. Returns a device_code (used by the device to poll for a token) and a user_code (shown to the user to enter at the verification_uri).

This endpoint requires a publishable API key; secret keys are rejected with a 403. Third-party OAuth must be enabled on the app; if it is not, the response returns error: "third_party_oauth_not_enabled" with a 403.

The endpoint is rate-limited to 10 requests per IP per minute. Excess requests receive a 429 response. The returned codes expire after expires_in seconds; once expired, a new authorization request must be initiated.

post/oauth/device/authorize

Request body

clientstring required

OAuth client ID (cli_...) identifying the application requesting authorization.

scopestring

Space-separated list of OAuth scopes to request, e.g. "read write". Omit to request only the default scopes configured for the client.

Example request

{
  "client": "string",
  "scope": "string"
}

Response

Successful response

device_codestring required

Opaque code identifying this device authorization session. Pass this value when polling the token endpoint; do not display it to the user.

expires_ininteger required

Number of seconds until the device_code and user_code expire. After expiry the user must restart the authorization flow.

intervalinteger required

Minimum number of seconds to wait between polling attempts on the token endpoint. Polling more frequently will result in a slow_down error.

user_codestring required

Short alphanumeric code the user must enter at verification_uri to authorize the device.

verification_uristring required

URL the user visits to enter the user_code and approve the authorization request.

verification_uri_completestring required

Full verification URL with the user_code pre-filled as a query parameter. Display this as a QR code or deep link to reduce manual entry.

Example response

{
  "device_code": "string",
  "expires_in": 1800,
  "interval": 5,
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://example.com",
  "verification_uri_complete": "string"
}