> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Copy a key from app.cadenya.com/account/apiKeys or create one with cadenya api-keys create, then set it as CADENYA_API_KEY. Keys belong to the account and reach the workspaces you assign them to.

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](https://app.cadenya.com/account/apiKeys) and set it where your code runs:

```bash .env theme={null}
CADENYA_API_KEY=your-api-key
```

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:

```bash theme={null}
cadenya api-keys create \
  --name "Petstore app (production)" \
  --workspace-assignment workspace-id=external_id:production \
  --permission objectives:manage
```

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:

| Command | What it does |
| - | - |
| `cadenya api-keys list` | Lists the keys that reach the workspace in `CADENYA_WORKSPACE_ID` (or `--workspace-id`), without their tokens. |
| `cadenya api-keys reveal <id>` | Returns the key with a new token. Earlier tokens keep working. A disabled key can't be revealed. |
| `cadenya api-keys rotate <id>` | Issues a new token and invalidates every earlier token for the key. |
| `cadenya api-keys disable <id>` | Stops the token from working, revokes the key's Widget Sessions, and keeps the key. `enable` turns the token back on, but revoked Widget Sessions stay revoked. |
| `cadenya api-keys add-workspace <id> --workspace-id <workspace>` | Assigns one more workspace. `remove-workspace` takes one away, except on a key with `allWorkspaces` set. |

The same operations live in the API reference, starting with [Create a new API key](https://cadenya.com/docs/api-reference/apikeyservice/create-a-new-api-key.md) (`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](https://cadenya.com/docs/guides/the-basics/widgets.md) shows the handoff.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.