Skip to main content
Caveman Cloud uses two separate credentials. The Cave API key authenticates you to Caveman Cloud. The upstream provider key authenticates to the model provider. They have different audiences, different rotation paths, and different error behavior when they are missing or invalid.

​
The two credentials

The Cave key carries your tenant and project scope. The upstream key is forwarded by the gateway to the provider on your behalf. When you store the upstream key in a Caveman Cloud provider connection, you can drop the x-cave-upstream-key header from requests.
Never commit either key to source control. Use environment variables or a secret manager.

​
Gateway authentication

Send the Cave API key on every request to the gateway. The gateway reads the x-cave-api-key header first and falls back to authorization: Bearer <key>, so both styles work. It resolves your organization and project from the key, then forwards the request upstream with the provider key.
Use authorization: Bearer when your SDK puts its apiKey there (for example, the OpenAI SDK with apiKey: CAVE_API_KEY). Use x-cave-api-key when the SDK’s apiKey slot must carry the provider key instead, as in the OpenAI and Anthropic integration examples.
Labels like x-cave-agent and x-cave-workflow identify traffic for reporting. They do not grant access. Tenant scope always comes from the verified API key, never from a request label or payload field.

​
Control API and console authentication

The console and the control API authenticate with the same identity system used by the gateway. When you sign in through the browser, the console obtains an access token for control-plane operations. The Cloud SDKs and CLI use the same token.

​
CLI sign-in

Install the cvm CLI and sign in once through the browser. The CLI reuses the credential saved by caveman login.
In headless environments such as CI, set CAVE_TOKEN and, for a private installation, CAVE_API_URL. Signed-out cvm commands exit with code 3 instead of hanging.
Non-secret config sits at ~/.caveman-cloud/config.json. Auth tokens go to the OS keychain when available, with a file fallback under ~/.caveman/credentials.

​
MCP and coding agents

Coding agents connect through the MCP endpoint using browser OAuth. Open Connect your coding agent in the dashboard. The approval binds one project and defaults to metadata reads; content, authoring, and paid execution stay opt-in. No Caveman CLI or gateway key is required for this path. OAuth uses S256 PKCE and issuer-bound authorization responses. There is no dynamic client registration.

​
Project scoping

Keys, traces, workloads, evals, and SQL queries are all scoped to a project. When using the CLI, you can target a project with:
  • --project UUID
  • The CAVE_PROJECT_ID environment variable
  • cvm context bind (writes .caveman-cloud.json in the repository)
  • The saved default project
SDK calls require projectId at initialization.

​
Key rotation and governance

Project owners and admins manage API keys under Governance, Keys in the console. You can create, revoke, and review key usage. Identity administration and credential lifecycle remain human-only: shared agents cannot create or rotate keys. A Cloud access token and a gateway inference key have different audiences. Do not use one where the other is expected.

​
Common auth errors

For SQL access, per-person columns need billing:read, payload columns need payload:read, and agent connections additionally need trace:read_payload. Project keys with sql:read can query their own project only.