Skip to main content
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, you can paste a token interactively or import a token instead of opening a browser:
Without a terminal, for example in a script, rig login stops and names what works instead: set RIG_API_KEY for each command (it isn’t saved), or pipe the key to rig login --import-token, which validates and saves it. Only a key the server rejects is reported as invalid; if the server can’t be reached, the error says so. Signing in also sets up SSH access from this machine. Inside a workspace you don’t sign in: the CLI there already acts as the workspace, and rig login and rig logout refuse. Once logged in, any command works without further setup, for example:

​
API keys

For GitHub deployments, use GitHub Actions OIDC credentials. For other backend services or agents that need account API access, create an 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:
--body takes inline JSON, a path to a JSON file, or - to read standard input; a body that isn’t valid JSON fails before anything is sent. When the server returns an error, rig api prints the response body as the server sent it, reports the HTTP status, and exits non-zero. With --output json, the error event carries status and body alongside code and message. Inside a workspace, rig api sends requests through the workspace bridge, which serves only that workspace’s routes.

​
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 ~/.config/rigbox/config.json.
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. Use an API key authorized to access the target app; a valid key for another owner is not sufficient:
Use the URL returned in the app details; do not infer the subdomain from a display name.
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