---
title: "Initiate a device authorization request"
method: POST
path: "/oauth/device/authorize"
---

# Initiate a device authorization request

`POST /oauth/device/authorize`

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.

## Request body

- object
  - `client` string, required — OAuth client ID (`cli_...`) identifying the application requesting authorization.
  - `scope` string — Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.

## Response `200`

Successful response

- DeviceAuthorizationResponse — The initial response from an OAuth 2.0 Device Authorization Grant request, containing the codes and URIs needed to complete device authentication.
  - `device_code` string, required — Opaque code identifying this device authorization session. Pass this value when polling the token endpoint; do not display it to the user.
  - `expires_in` integer, required — Number of seconds until the `device_code` and `user_code` expire. After expiry the user must restart the authorization flow.
  - `interval` integer, 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_code` string, required — Short alphanumeric code the user must enter at `verification_uri` to authorize the device.
  - `verification_uri` string, required — URL the user visits to enter the `user_code` and approve the authorization request.
  - `verification_uri_complete` string, 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.

## Other responses

- `400` — Bad request
- `403` — Forbidden
- `429` — Rate limited

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)