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

# Authentication

> Authenticate the qumod CLI via OAuth 2.0 Device Flow or API tokens.

# CLI Authentication

`qumod` supports two authentication workflows:

1. **Interactive Browser Login (Device Authorization Flow)**: Ideal for developers working locally on workstations.
2. **Headless Token Authentication (`QUMO_TOKEN`)**: Ideal for CI/CD runners, Docker containers, and Coding Agents.

***

## 1. Interactive Device Authorization Flow

Run the `login` command:

```bash theme={null}
qumod login
```

`qumod` will initiate the OAuth 2.0 Device Authorization Flow (RFC 8628):

```text theme={null}
Initiating device authorization flow on https://api.qumo.dev...

  To authenticate, visit:
    https://console.qumo-deploy.com/device

  And enter this one-time code:
    ABCD-EFGH

✔ Browser opened automatically. Polling for authorization...
```

1. The CLI will attempt to launch your system browser automatically.
2. If running over SSH or a headless display, open the displayed URL manually and enter the one-time user code.
3. Sign in using your Qumo Deploy account and click **Approve**.
4. The CLI polls the control plane and automatically saves the issued session token to `~/.qumo/config.json`.

***

## 2. Headless Authentication (CI/CD & Coding Agents)

In automated environments where interactive prompts are impossible, pass credentials via an environment variable or flag:

### Environment Variable (Recommended for CI/CD)

Export `QUMO_TOKEN` with an API Key or Personal Access Token (PAT):

```bash theme={null}
export QUMO_TOKEN="sec_live_example123..."
qumod whoami
```

### Command Flag

You can also pass the token per-invocation using `--token`:

```bash theme={null}
qumod whoami --token "sec_live_example123..."
```

<Note>
  Flags take precedence over environment variables, which take precedence over saved tokens in `~/.qumo/config.json`.
</Note>

***

## Checking Current Identity (`whoami`)

To confirm authentication status, organization details, and IAM roles:

```bash theme={null}
qumod whoami
```

Sample output:

```text theme={null}
  Logged in as:   alice@example.com
  Organization:   Acme Streaming Corp
  Role:           tenant_admin
  API Endpoint:   https://api.qumo.dev

  Tenants:
    - Acme Streaming Corp (ten_8f29acb0) [tenant_admin]
```

### JSON Mode for Scripts and Agents

Pass `--json` for structured, machine-readable output:

```bash theme={null}
qumod whoami --json
```

```json theme={null}
{
  "user": {
    "id": "usr_9918231",
    "email": "alice@example.com",
    "name": "Alice Developer"
  },
  "organization": {
    "id": "ten_8f29acb0",
    "name": "Acme Streaming Corp"
  },
  "role": "tenant_admin",
  "apiUrl": "https://api.qumo.dev",
  "memberships": [
    {
      "tenant_id": "ten_8f29acb0",
      "tenant_name": "Acme Streaming Corp",
      "role_id": "tenant_admin"
    }
  ]
}
```

***

## Logging Out

To clear local credentials and invalidate the active session:

```bash theme={null}
qumod logout
```

```text theme={null}
✔ Successfully logged out. Removed cached credentials.
```