> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnimux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Public hosts only: console https://omnimux.ai/dashboard · API https://api.omnimux.ai · docs https://docs.omnimux.ai.
> Gateway auth is Authorization: Bearer sk-… on https://api.omnimux.ai/v1 (OpenAI-compatible Chat Completions and related paths).
> Discover pages from /llms.txt; full site dump /llms-full.txt; product skill /skill.md; docs search MCP /mcp. Prefer .md page URLs for Markdown.
> Default docs locale is en; zh mirrors the same relative paths. Do not invent model ids not present on live pricing or the complete API pages.

# Device Code Login

> RFC 8628-style device login: request device_code → browser approve → poll for access_token

* Account management user API (CLI / headless login)
* **Code request and token poll need no auth**; approve/deny need a logged-in browser session
* The returned `access_token` is for `https://omnimux.ai` user APIs (with `New-Api-User`)

## Identity

| Field      | Value        |
| ---------- | ------------ |
| Series     | Account      |
| Capability | Device login |

## Endpoints

| Step                                    | Method                  | Path                                                 | Auth            |
| --------------------------------------- | ----------------------- | ---------------------------------------------------- | --------------- |
| 1. Request device code                  | `POST`                  | `/api/user/device/code`                              | None            |
| 2. Browser approval                     | Open `verification_uri` | Console / CLI login page                             | Browser session |
| 3. Poll for token                       | `POST`                  | `/api/user/device/token`                             | None            |
| 4. Approve / deny (optional, logged-in) | `POST`                  | `/api/user/device/approve` · `/api/user/device/deny` | User session    |

Base URL: `https://omnimux.ai`

## Authorization

| Step                             | Requirement                                                                         |
| -------------------------------- | ----------------------------------------------------------------------------------- |
| `device/code` · `device/token`   | **No** `Authorization` / `New-Api-User`                                             |
| `device/approve` · `device/deny` | Logged-in user (console session); body includes `user_code`                         |
| After token issued               | Other user APIs: `Authorization: Bearer <access_token>` + `New-Api-User: <user_id>` |

AI gateway and social-data APIs still use `sk-` tokens on `https://api.omnimux.ai` — a different credential surface. See [Connection & usage](/en/faqs/connection-usage).

## Body / parameters

### `POST /api/user/device/code`

| Field         | Type   | Required | Description                  |
| ------------- | ------ | -------- | ---------------------------- |
| `client_name` | string | no       | Client label (e.g. `my-cli`) |

### `POST /api/user/device/token`

| Field         | Type   | Required | Description                                                    |
| ------------- | ------ | -------- | -------------------------------------------------------------- |
| `device_code` | string | yes      | `device_code` from step 1                                      |
| `grant_type`  | string | no       | If set, must be `urn:ietf:params:oauth:grant-type:device_code` |

Poll at the response `interval` (default \~5s); polling faster returns `slow_down`.

## Response

### Step 1 · 200 (code issued)

| Field                            | Description                              |
| -------------------------------- | ---------------------------------------- |
| `data.device_code`               | Secret for the device (poll with this)   |
| `data.user_code`                 | Short code the user types in the browser |
| `data.verification_uri`          | Approval page URL                        |
| `data.verification_uri_complete` | URL with prefilled `user_code`           |
| `data.expires_in`                | Lifetime in seconds (default 900)        |
| `data.interval`                  | Recommended poll interval (seconds)      |

### Step 3 · success (approved)

| Field               | Description                     |
| ------------------- | ------------------------------- |
| `data.access_token` | System access token (PAT)       |
| `data.token_type`   | `Bearer`                        |
| `data.user_id`      | User id (use as `New-Api-User`) |
| `data.username`     | Username                        |

### Step 3 · pending / errors (often HTTP 200 with `success: false`)

| `code`                            | Meaning                   |
| --------------------------------- | ------------------------- |
| `authorization_pending`           | User has not approved yet |
| `slow_down`                       | Polling too fast          |
| `access_denied`                   | User denied               |
| `expired_token` / `invalid_grant` | Expired or invalid        |

More error semantics: [Connection & usage](/en/faqs/connection-usage).

<Panel>
  <RequestExample>
    ```bash 1. Request device code theme={null}
    curl --request POST \
      --url https://omnimux.ai/api/user/device/code \
      --header 'Content-Type: application/json' \
      --data '{"client_name":"my-cli"}'
    ```

    ```bash 2. Poll for token theme={null}
    curl --request POST \
      --url https://omnimux.ai/api/user/device/token \
      --header 'Content-Type: application/json' \
      --data '{"device_code":"<device_code>","grant_type":"urn:ietf:params:oauth:grant-type:device_code"}'
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 code issued theme={null}
    {
      "success": true,
      "data": {
        "device_code": "...",
        "user_code": "ABCD-EFGH",
        "verification_uri": "https://omnimux.ai/cli/login",
        "verification_uri_complete": "https://omnimux.ai/cli/login?user_code=ABCD-EFGH",
        "expires_in": 900,
        "interval": 5
      }
    }
    ```

    ```json pending theme={null}
    {
      "success": false,
      "code": "authorization_pending",
      "message": "authorization pending",
      "interval": 5
    }
    ```

    ```json 200 approved theme={null}
    {
      "success": true,
      "data": {
        "access_token": "...",
        "token_type": "Bearer",
        "user_id": 1,
        "username": "alice"
      }
    }
    ```

    ```json denied theme={null}
    {
      "success": false,
      "code": "access_denied",
      "message": "authorization denied"
    }
    ```
  </ResponseExample>
</Panel>