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

# Authentication

Browser device flow for humans. Env-var or --api-key for CI and AI agents.

# CLI authentication

The CLI accepts an API key from three places, in priority order:

1. `--api-key` flag on the command line.
2. `RIQ_API_KEY` environment variable.
3. `~/.rogeriq/config.json` (created by `rogeriq auth login`).

## Browser login (recommended for humans)

```bash
rogeriq auth login
```

Opens [rogeriq.com/device?code=XXXX-XXXX](https://rogeriq.com/device) in
your browser, polls every 5 seconds, and saves the minted API key
locally. The code is also printed to your terminal so you can paste it
manually if the browser doesn't open (SSH / headless boxes).

**Run the command**

```bash
    rogeriq auth login
    ```
  **Approve in the browser**

You'll be prompted to sign in (or signup) if you aren't already. If you
    belong to exactly one organization, the code is auto-submitted. Otherwise,
    pick the org you want the CLI to bind to.
  **Verify**

```bash
    rogeriq auth whoami
    # api_key_prefix: riq_a1b2c3d4...
    # api_base:       https://api.rogeriq.com
    # org_id:         org_xxxxx
    ```

Flags:

| Flag | Default | Purpose |
|------|---------|---------|
| `--no-browser` | `false` | Print the URL but don't auto-open. SSH / headless. |
| `--api-base` | `https://api.rogeriq.com` | Point at a non-production deployment. |
| `--client-name` | Auto from `$USER@$HOSTNAME` | Label shown on the consent screen. Set to `claude-code`, `cursor`, etc. when running from an agent. |

## API key (CI, scripts, AI agents)

Skip the browser flow entirely:

```bash
rogeriq auth login --api-key riq_xxx
```

Or pass per-invocation via env var (no config file needed):

```bash
export RIQ_API_KEY=riq_xxx
export RIQ_PROJECT_ID=prj_xxx
rogeriq conversations list
```

**Never run `rogeriq auth login` (no args) from an AI agent.** The browser
device flow blocks for up to 10 minutes waiting for human approval.
Always pass `--api-key` or set `RIQ_API_KEY` for agent / CI workflows.

## Whoami / logout

```bash
rogeriq auth whoami
rogeriq auth logout       # clears ~/.rogeriq/config.json
```

## Where the key is stored

| Path | Contents |
|------|----------|
| `~/.rogeriq/config.json` (mode 0600) | `{ "apiKey": "riq_...", "apiBase": "...", "orgId": "org_...", "projectId": "prj_..." }` |

## Scopes

API keys can be coarse or granular. See the [scope reference](/api/scopes).

| Scope | Grants |
|-------|--------|
| `admin` | Everything. |
| `write` | All `*:read` + `*:write`. Not `*:admin`. |
| `read` | All `*:read`. |
| `<resource>:admin` | `:read` + `:write` + `:admin` on that resource. |
| `<resource>:write` | `:read` + `:write` on that resource. |
| `<resource>:read` | `:read` on that resource only. |

Resources: `conversations`, `messages`, `contacts`, `kb`, `agent`,
`widget`, `integrations`, `forms`, `beacons`, `webhooks`, `projects`,
`analytics`, `audit`.

Create a least-privilege key for an AI that only drafts KB articles and
reads conversations:

```bash
rogeriq keys create kb-writer --scopes kb:write,conversations:read
```

## Rotation

Create a new key, update your config / secrets, then revoke the old one.
Revocation is instant.

```bash
rogeriq keys create cli-laptop
# Paste the displayed riq_... into RIQ_API_KEY or rogeriq auth login --api-key
rogeriq keys list
rogeriq keys revoke key_old_id
```