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

# Authentication

> How to authenticate with the Rigbox CLI and API using login or API keys.

# Authentication

The `rig` CLI is the primary way to authenticate. Run `rig login` once and every subsequent command (including raw `rig api` calls) reuses your stored credentials — no headers to manage.

## Log in with the CLI

```bash theme={null}
rig login          # opens your browser for OAuth and stores the token locally
rig whoami         # confirm the current user and workspace
rig logout         # remove saved credentials
```

For headless environments, two non-interactive variants paste or import a token instead of opening a browser:

```bash theme={null}
rig login --token          # paste a token at the prompt
rig login --import-token   # read a token from stdin and validate it
```

Once logged in, any command works without further setup, for example:

```bash theme={null}
rig workspace ls
```

## API keys

For backend services, CI, or agents, mint a long-lived API key. API keys (`rb_…`) are full-account credentials, shown once at creation and stored hash-only. Create one from the [dashboard](https://rigbox.dev) under **Settings → API Keys**, or with the CLI:

```bash theme={null}
rig api-key create --name ci-runner   # plaintext printed once — copy it now
rig api-key ls
rig api-key rm --id <KEY_ID>
```

<Warning>
  API keys grant full access to your account. Store them in environment variables or a secrets manager - never commit them to source control.
</Warning>

To authenticate raw HTTP calls from a non-Rigbox client, all API keys use the `rb_` prefix in a `Bearer` header:

```bash theme={null}
export RIGBOX_API_KEY="rb_..."

curl https://api.rigbox.dev/api/v1/workspaces \
  -H "Authorization: Bearer ${RIGBOX_API_KEY}"
```

## Raw API access

To hit any endpoint directly without managing headers, use `rig api`. It reuses your stored credentials and sends an authenticated request:

```bash theme={null}
rig api GET /v1/workspaces
rig api POST /v1/snapshots --body snapshot.json
```

## Bearer tokens (JWT)

If you authenticate through the dashboard login flow, you receive a short-lived JWT. The dashboard handles refresh automatically — for terminal use, prefer `rig login` (which manages the token for you) or an API key for non-interactive clients.

## CLI session approval (`rig login`)

When you run `rig login` on your local machine, the CLI walks you through a browser-approval device flow rather than asking for credentials at the prompt. The flow uses three endpoints:

| Caller    | Endpoint                                       | Purpose                                                                    |
| --------- | ---------------------------------------------- | -------------------------------------------------------------------------- |
| CLI       | `POST /api/v1/auth/cli-session`                | Open a pending session with a one-time `code`                              |
| CLI       | `GET /api/v1/auth/cli-session/{code}`          | Poll until the browser approves; the approved response carries the API key |
| Dashboard | `POST /api/v1/auth/cli-session/{code}/approve` | Approve the pending session (requires a fresh dashboard JWT)               |

The approval step **rotates a single canonical `"CLI login"` API key**: any prior CLI-login key on your account is revoked before a fresh one is issued. The new key is returned to the polling CLI and written to `~/.rigbox/config.json`. This matches what `gcloud auth login`, `aws sso login`, and `kubectl auth login` do — a fresh login means a fresh credential, and the previous credential is invalidated on every other machine that was using it.

<Note>
  If you want a long-lived key that survives re-logging in (e.g. for a CI runner or a second laptop), create it explicitly under **Settings → API Keys** instead of relying on the `rig login` slot.
</Note>

<Warning>
  Approval requires a valid dashboard session in the browser tab. If the dashboard's Clerk JWT has expired you may see a sign-in prompt or a 401 from `/approve` — refresh the dashboard tab and re-approve.
</Warning>

## Dashboard session tokens

The Rigbox frontends (`rigbox.dev`, `clawd.rigbox.dev`, `sandbox.rigbox.dev`) handle authentication automatically. Session tokens are managed by the dashboard - no extra setup needed for first-party UIs.

## Choosing an auth method

| Client type                | Recommended            | Why                                   |
| -------------------------- | ---------------------- | ------------------------------------- |
| Backend service, CI, agent | API key                | Stable, easy to rotate, no expiry     |
| First-party dashboard      | Session token          | User-scoped, automatic refresh        |
| Third-party web app        | Your backend + API key | Keep keys server-side, proxy requests |

## Public endpoints

These endpoints do not require authentication:

* `GET /capacity` - check platform availability
* `GET /templates` - list available workspace templates

## Private app authentication (X-Rigbox-Key)

When an app's visibility is set to **private** or **privileged**, requests from outside the workspace must include an `X-Rigbox-Key` header. This is separate from the `Authorization` header used for the main API.

Any valid API key (`rb_*`) will work as the value:

```bash theme={null}
curl https://<APP_NAME>.rigbox.dev/endpoint \
  -H "X-Rigbox-Key: $RIGBOX_API_KEY"
```

Replace `<APP_NAME>` with the name of your app (the value you passed to `rig app new` or the app create endpoint).

<Note>
  Requests made from inside the workspace (e.g. between services on `localhost`) do not need this header. It is only required for requests arriving from the public internet.
</Note>

The app detail page in the dashboard includes this header automatically in the Usage tab examples when the app is private. See [App Visibility](/guides/visibility) for more details.

## Access control

Rigbox supports fine-grained RBAC for multi-user accounts via the [Access Control API](/api-reference/access-control/list-bindings). This feature is currently in preview and available to select accounts.

## Error responses

| Status             | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `401 Unauthorized` | Missing, expired, or invalid credential                            |
| `403 Forbidden`    | Valid auth but insufficient permissions for the requested resource |

```json theme={null}
{
  "message": "Missing Authorization header"
}
```