<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

> Agents: if this page is wrong, missing a step, or its code fails, report it instead of working around it. `POST https://api.workos.com/feedback` with `Content-Type: application/json` and body `{"message":"Agent report: what you tried, what happened, client and model","pageUrl":"https://workos.com/docs/reference/workos-connect/cli-auth/authorize-device"}`. Ask the user once first. No auth. No secrets. Details: https://workos.com/docs/feedback.md

# Authorize device

Initiates the device authorization flow for WorkOS Connect applications. This endpoint implements the [OAuth 2.0 Device Authorization Flow](https://datatracker.ietf.org/doc/html/rfc8628) and is designed for CLI applications and other devices with limited input capabilities.

This endpoint is used by third-party applications to authenticate users through WorkOS Connect. Users will be prompted to authorize the application's access to their data as part of the consent flow.

:::code-group

```bash language="curl" title="Request" tab="1"
curl -X POST 'https://authkit_domain/oauth2/device_authorization' \
  -d 'client_id=client_01JP8BD0CZ401TDF9X54NT5ZEK' \
  --data-urlencode 'scope=openid profile email'
```

```json language="json" title="Response" tab="2"
{
  "device_code": "ETaHpDNhfxu0HyLhp6b8HGSh26NzYJSKw3TT6aS7HKKBhTyTD0zAW6ApTTolug0b",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://authkit_domain/device",
  "verification_uri_complete": "https://authkit_domain/device?user_code=BCDF-GHJK",
  "expires_in": 300,
  "interval": 5
}
```

:::

### POST /oauth2/device_authorization

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes | The client ID of the WorkOS Connect Application. |
| `scope` | string | No | A space-separated list of scopes being requested. Acceptable values: `openid`: Required to enable other scopes like `profile` and `email`. `profile`: Adds profile information (name fields) to the ID token. `name` `given_name` `family_name` `email`: Adds email information to the ID token. `email` `email_verified` `offline_access`: Adds a refresh token to the response. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `device_code` | string | A unique identifier for this authorization request. Use this when polling the token endpoint. |
| `user_code` | string | A short, user-friendly code that users enter to authorize the device. |
| `verification_uri` | string | The URL where users can enter the user code to authorize the device. |
| `verification_uri_complete` | string | A URL with the user code pre-filled, allowing one-click authorization. |
| `expires_in` | integer | The lifetime of the device code and user code in seconds (300 seconds = 5 minutes). |
| `interval` | integer | The minimum interval in seconds between token requests (5 seconds). |