Skip to main content
An API key is how your code, the CLI, and the MCP server act on your Cadenya account. Keys belong to the account, not to a workspace. Each one has access to the workspaces you assign it to, or every workspace when allWorkspaces is set. And a key’s scopes are the same in every workspace it reaches.

​
Get a key

You already have one. Cadenya creates it when you sign up: it’s called Default API Key, its external ID is default, it has full access (*), and it reaches every workspace, including the ones you create later. You can delete it if you’d like and opt for more granular scopes. Copy it from the API keys page and set it where your code runs:
.env
The SDKs and the CLI read CADENYA_API_KEY from the environment. The cURL examples in these docs send it as Authorization: Bearer ${CADENYA_API_KEY}.

​
Create a key for one workspace

The default key can do anything, anywhere. That’s handy on your laptop and a lot of blast radius on a server. Give each server its own key, with one workspace and only the scopes that server needs. Create it on the API keys page, or with the CLI:
A key takes workspace assignments or --all-workspaces, not both. The response includes the token in spec.token, and later reads leave it out. Need it again? cadenya api-keys reveal <id> mints a new token for the key, and the earlier ones keep working. Creating a key takes the api_keys:manage scope, and a key that reaches every workspace also takes api_keys:admin. A key can only hand out workspaces and scopes it already has, so no key mints a bigger key than itself. Without api_keys:admin, a key manages only the keys it created, plus the keys those keys created.

​
Scopes

A scope is resource:verb, such as objectives:manage. The verbs are read and manage, and manage includes read. Two families break the pattern: api_keys also takes admin (which includes manage), and secrets and account take only manage. The scope * grants everything. And a key with no scopes can call only the endpoints that need none. These resources take scopes: agents, agent_pools, models, objectives, tools, memory, api_keys, workspaces, widgets, widget_sessions, tenants, endpoints (trusted endpoints), secrets, and account. One scope needs another: tools:manage needs secrets:manage, because Tool Set headers and base URLs read workspace secrets.

​
Manage a key

Every command takes the key’s apikey_ ID or its external ID, so external_id:default is the default key: The same operations live in the API reference, starting with Create a new API key (POST /v1/account/api_keys).

​
Keep keys on your server

An API key never goes in browser code. For a chat in your web app, your server mints a short-lived Widget Session and hands the browser its token. The Widgets guide shows the handoff.