docs(api): add OAuth device authorization flow documentation (#15977)

Add documentation for the OAuth 2.0 Device Authorization Grant (RFC
8628) to the API authentication docs.

This documents the device code flow implemented in
getsentry/sentry@d4e4b74, which enables
headless clients (CLI tools, CI/CD pipelines, Docker containers) to
authenticate without a browser on the device.

The new section covers:
- When to use the device flow vs standard OAuth
- Requesting device codes from `/oauth/device/code/`
- Displaying user codes and verification URLs
- Polling the token endpoint with proper interval handling
- Error responses (`authorization_pending`, `slow_down`,
`access_denied`, `expired_token`)
- Complete Python example implementation

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: dcramer

docs/api/auth.mdx

@@ -113,6 +113,179 @@ curl -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 
 A Sentry user can belong to multiple organizations. The access token only provides access to the specific organization the user selected during the OAuth flow. The `/api/0/organizations/` endpoint will only return the connected organization.
 
+### Device Authorization Flow
+
+The device authorization grant ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) enables applications on devices without a browser or with limited input capabilities to obtain authorization. This is ideal for CLI tools, CI/CD pipelines, Docker containers, and other headless environments where redirecting to a browser on the same device isn't practical.
+
+**How it works:** Your application requests a device code, displays a short user code to the user, and polls for authorization. The user visits Sentry in their browser (on any device), enters the code, and approves the request. Once approved, your application receives an access token.
+
+#### Step 1: Request Device Code
+
+Request a device code from the device authorization endpoint:
+
+```bash
+curl -X POST https://sentry.io/oauth/device/code/ \
+  -d client_id={CLIENT_ID} \
+  -d scope=org:read%20project:read
+```
+
+**Parameters:**
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `client_id` | Yes | Your registered client ID |
+| `scope` | No | Space-separated list of [permissions](/api/permissions/) |
+
+**Response:**
+```json
+{
+  "device_code": "a1b2c3d4e5f6...",
+  "user_code": "ABCD-EFGH",
+  "verification_uri": "https://sentry.io/oauth/device/",
+  "verification_uri_complete": "https://sentry.io/oauth/device/?user_code=ABCD-EFGH",
+  "expires_in": 600,
+  "interval": 5
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `device_code` | Secret code your application uses to poll for the token |
+| `user_code` | Short code the user enters to authorize (format: `XXXX-XXXX`) |
+| `verification_uri` | URL where the user should go to enter the code |
+| `verification_uri_complete` | URL with user code pre-filled (useful for QR codes or clickable links) |
+| `expires_in` | Seconds until the codes expire (default: 600 / 10 minutes) |
+| `interval` | Minimum seconds between polling requests (default: 5) |
+
+#### Step 2: Display Instructions to User
+
+Display the user code and verification URL to your user:
+
+```
+To authenticate, visit: https://sentry.io/oauth/device/
+Enter code: ABCD-EFGH
+```
+
+The user code uses an unambiguous character set (no 0/O, 1/I/L confusion) for easy entry.
+
+#### Step 3: Poll for Token
+
+While the user authorizes in their browser, poll the token endpoint:
+
+```bash
+curl -X POST https://sentry.io/oauth/token/ \
+  -d client_id={CLIENT_ID} \
+  -d device_code={DEVICE_CODE} \
+  -d grant_type=urn:ietf:params:oauth:grant-type:device_code
+```
+
+Poll at the `interval` specified in the device authorization response (default: 5 seconds). While waiting for the user, you'll receive:
+
+```json
+{
+  "error": "authorization_pending",
+  "error_description": "The authorization request is still pending."
+}
+```
+
+Continue polling until you receive a token or an error.
+
+#### Step 4: Receive Access Token
+
+Once the user approves, the token endpoint returns:
+
+```json
+{
+  "access_token": "{ACCESS_TOKEN}",
+  "refresh_token": "{REFRESH_TOKEN}",
+  "expires_in": 2591999,
+  "expires_at": "2024-11-27T23:20:21.054320Z",
+  "token_type": "bearer",
+  "scope": "org:read project:read",
+  "user": {
+    "id": "123",
+    "name": "Jane Doe",
+    "email": "[email protected]"
+  }
+}
+```
+
+#### Device Flow Error Responses
+
+| Error | Description | Action |
+|-------|-------------|--------|
+| `authorization_pending` | User hasn't completed authorization yet | Continue polling |
+| `slow_down` | Polling too frequently | Increase interval by 5 seconds |
+| `access_denied` | User denied the authorization request | Stop polling, notify user |
+| `expired_token` | Device code has expired | Restart the flow from step 1 |
+
+#### Device Flow Example
+
+```python
+import time
+import requests
+
+CLIENT_ID = 'your-client-id'
+DEVICE_AUTH_URL = 'https://sentry.io/oauth/device/code/'
+TOKEN_URL = 'https://sentry.io/oauth/token/'
+
+def authenticate():
+    # Step 1: Request device code
+    response = requests.post(DEVICE_AUTH_URL, data={
+        'client_id': CLIENT_ID,
+        'scope': 'org:read project:read'
+    })
+    data = response.json()
+
+    device_code = data['device_code']
+    user_code = data['user_code']
+    verification_uri = data['verification_uri']
+    verification_uri_complete = data.get('verification_uri_complete')
+    interval = data.get('interval', 5)
+    expires_in = data['expires_in']
+
+    # Step 2: Display instructions
+    print(f"\nTo authenticate, visit: {verification_uri}")
+    print(f"Enter code: {user_code}")
+    if verification_uri_complete:
+        print(f"\nOr open this link directly: {verification_uri_complete}")
+    print()
+
+    # Step 3: Poll for token
+    deadline = time.time() + expires_in
+    while time.time() < deadline:
+        time.sleep(interval)
+
+        response = requests.post(TOKEN_URL, data={
+            'client_id': CLIENT_ID,
+            'device_code': device_code,
+            'grant_type': 'urn:ietf:params:oauth:grant-type:device_code'
+        })
+        result = response.json()
+
+        if 'access_token' in result:
+            # Step 4: Success
+            print("Authentication successful!")
+            return result['access_token'], result['refresh_token']
+
+        error = result.get('error')
+        if error == 'authorization_pending':
+            continue
+        elif error == 'slow_down':
+            interval += 5
+        elif error == 'access_denied':
+            raise Exception("User denied authorization")
+        elif error == 'expired_token':
+            raise Exception("Device code expired")
+        else:
+            raise Exception(f"Unexpected error: {error}")
+
+    raise Exception("Authorization timed out")
+
+if __name__ == '__main__':
+    access_token, refresh_token = authenticate()
+    print(f"Access token: {access_token[:20]}...")
+```
+
 ### PKCE (Proof Key for Code Exchange)
 
 PKCE protects against authorization code interception attacks and is strongly recommended for all OAuth clients.