> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Device Flow

> OAuth 2.0 device authorization flow used by the SuperBox CLI

## Overview

The device authorization flow lets the SuperBox CLI authenticate users without embedding browser logic. The CLI obtains a device code, displays a URL for the user to visit, then polls until the user completes login.

<Info>
  This is the flow used internally by `superbox auth login --provider google` and `superbox auth login --provider github`.
</Info>

## Step 1 - Start Device Session

Request a device code and user code.

### Endpoint

```
POST /api/v1/auth/device/start
```

### Request Body

<ParamField body="provider" type="string" required>
  OAuth provider: `google` or `github`
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.superbox.ai/api/v1/auth/device/start \
    -H "Content-Type: application/json" \
    -d '{"provider": "google"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.superbox.ai/api/v1/auth/device/start",
      json={"provider": "google"},
  )

  data = response.json()
  print(f"Visit: {data['verification_uri']}")
  print(f"Code:  {data['user_code']}")
  ```
</CodeGroup>

### Response (200)

<ResponseField name="device_code" type="string">
  Internal code used when polling. Keep this private.
</ResponseField>

<ResponseField name="user_code" type="string">
  Short code the user enters on the verification page (e.g., `ABCD-1234`).
</ResponseField>

<ResponseField name="verification_uri" type="string">
  URL for the user to open in a browser.
</ResponseField>

<ResponseField name="expires_in" type="number">
  Seconds until the device code expires (default: 600).
</ResponseField>

<ResponseField name="interval" type="number">
  Recommended polling interval in seconds (default: 5).
</ResponseField>

```json theme={null}
{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "ABCD-1234",
  "verification_uri": "https://superbox.1mindlabs.org/device",
  "expires_in": 600,
  "interval": 5
}
```

## Step 2 - User Authorizes

Display the `verification_uri` and `user_code` to the user. They open the URL in a browser, log in with the selected provider, and enter the code.

```
GET /api/v1/auth/device
```

This endpoint serves the browser-based verification form. You do not need to call it directly from the CLI.

## Step 3 - Poll for Token

Poll until the user completes authorization.

### Endpoint

```
POST /api/v1/auth/device/poll
```

### Request Body

<ParamField body="device_code" type="string" required>
  The device code returned in Step 1
</ParamField>

### Status Codes

| Status | Meaning                                              |
| ------ | ---------------------------------------------------- |
| `200`  | Authorization complete. Response contains the token. |
| `428`  | Still waiting. Continue polling.                     |
| `429`  | Polling too fast. Increase interval.                 |
| `400`  | Device code expired or invalid.                      |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.superbox.ai/api/v1/auth/device/poll \
    -H "Content-Type: application/json" \
    -d '{"device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS"}'
  ```

  ```python Python (polling loop) theme={null}
  import requests
  import time

  device_code = "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS"
  interval = 5

  while True:
      response = requests.post(
          "https://api.superbox.ai/api/v1/auth/device/poll",
          json={"device_code": device_code},
      )

      if response.status_code == 200:
          data = response.json()
          print("Authentication successful!")
          print(f"Token: {data['id_token']}")
          break
      elif response.status_code == 428:
          print("Waiting for authorization...")
          time.sleep(interval)
      elif response.status_code == 429:
          interval += 5
          time.sleep(interval)
      else:
          print(f"Error: {response.json()}")
          break
  ```
</CodeGroup>

### Success Response (200)

```json theme={null}
{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "refresh_token": "AMf-vByW3...",
  "expires_in": 3600,
  "email": "user@example.com",
  "local_id": "abc123def456"
}
```

### Pending Response (428)

```json theme={null}
{
  "status": "pending",
  "message": "Authorization pending"
}
```