API Reference
camelRun API authentication: keys, tokens and OAuth
How to authenticate to camelRun: API keys for your servers, agent tokens, browser tokens for users, and OAuth for coding agents over MCP.
View as Markdown · Docs index for coding agents
Every request to https://run.camelai.com sends a token as
Authorization: Bearer <token>. Which token depends on who is calling.
| Token | Looks like | Who holds it | What it can do |
|---|---|---|---|
| API key | art_... | Your servers | Everything in your account: create, run and delete agents, manage definitions, keys, channels and webhooks |
| Agent token | Returned when an agent is made | The SDK, on your server | Run that one agent and nothing else |
| Browser token | Minted per user | A browser | Read one agent's events, state, history and inputs for up to an hour |
| OAuth access token | Issued to MCP clients | A coding agent | Act as your account at /mcp. In the REST API, only agents, runs, definitions, workspaces, inputs and reads of the account (see below) |
API keys
Create API keys in the console under
API keys, or with POST /v1/tokens. Each key has full access to your
account, so give each application or script its own and revoke any you no
longer use.
The SDKs and the CLI read CAMELAI_API_KEY from the environment:
export CAMELAI_API_KEY=art_...
curl https://run.camelai.com/v1/me -H "Authorization: Bearer $CAMELAI_API_KEY"GET /v1/me returns your tenant id (which served tools
need) and your defaultModel.
Never put an API key in browser code, a mobile app, or a repository. Browsers get browser tokens instead.
Agent tokens
When an agent is made, POST /v1/agents returns its id and token. The SDKs
use the token for the agent's own connection (/clients/{id}/...), and keep it
out of logs and JSON. You rarely need it yourself: upserting by key with your API
key gets the agent again. An agent's token can't change what only the account
may, such as keyScope, spendLimit or modelHeaders.
Browser tokens
POST /v1/agents/{id}/browser-tokens mints a token that reads one agent, from
any origin, for 5 to 3,600 seconds (default 900). See
Show an agent in a browser.
OAuth for coding agents
The hosted MCP server at https://run.camelai.com/mcp signs clients in with
OAuth 2.1, as MCP's authorization spec describes. Access tokens last an hour,
and refresh tokens last 30 days and rotate on each use. Connected apps appear on
the console's API keys page under Connected apps, where you revoke them (or
DELETE /v1/oauth/grants/{id}). See CLI and MCP server.
In the REST API, an OAuth access token reaches your agents (not their tokens)
with their runs, inputs, schedules and mounts, stateless runs, definitions,
workspaces, and images, transcription and speech, and reads your models,
providers, usage and billing. It can't make a credential (API, agent or browser
tokens, signed links) or send your data somewhere new (webhooks, trace export,
channels, provider keys and endpoints), and volumes, computers and the account
export are closed to it too: each answers 403. Revoking the grant leaves no
access behind.
Identity tokens for your servers
When camelRun calls your served tools, it sends
its own signed token (an EdDSA JWT) saying which agent the call is for and who is
acting. Verify it against https://run.camelai.com/.well-known/jwks.json.
See Identity.