Skip to main content

​
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

For headless environments, two non-interactive variants paste or import a token instead of opening a browser:
Once logged in, any command works without further setup, for example:

​
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 under Settings → API Keys, or with the CLI:
API keys grant full access to your account. Store them in environment variables or a secrets manager - never commit them to source control.
To authenticate raw HTTP calls from a non-Rigbox client, all API keys use the rb_ prefix in a Bearer header:

​
Raw API access

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

​
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: 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.
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.
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.

​
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

​
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:
Replace <APP_NAME> with the name of your app (the value you passed to rig app new or the app create endpoint).
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.
The app detail page in the dashboard includes this header automatically in the Usage tab examples when the app is private. See App Visibility for more details.

​
Access control

Rigbox supports fine-grained RBAC for multi-user accounts via the Access Control API. This feature is currently in preview and available to select accounts.

​
Error responses