Link with secret keys

A secret key is a P-256 signing key for one agent. The key is the complete credential, so anyone who holds it can act as that agent, within the agent's policy.

You'll use a secret key wherever catena link cannot keep a credential. Common examples include:

• A cloud sandbox that starts fresh for each task (e.g., Claude, Codex, or Cursor cloud agents)
• A CI job
• A serverless function
• A service you deploy

If your agent runs on a machine or VM that keeps its home directory, we recommend catena link instead.

Create a key

1. In the console, open the agent from the Agents page.
2. Select the Secret keys tab, then click Create secret key.
3. Name the key for where it will run (such as production-worker).
4. Copy the key. We show it only once.

Creating and revoking keys requires the admin role and a signed-in console session. An agent can hold several keys (for example, one per deployment).

Use a key

Set the key as CATENA_SECRET_KEY in the host's secret settings, where both the CLI and the SDK read it:

export CATENA_SECRET_KEY=...
npx -y @catena/cli@latest whoami

import { createCatenaClient } from "@catena/sdk"

// Reads CATENA_SECRET_KEY when privateKeyHex is omitted.
const client = createCatenaClient()
const agent = await client.whoami()

There's no link step on the host. Each command signs with the key and does not read a profile, unless the command passes --profile.

Note

Precedence over profiles

When CATENA_SECRET_KEY is set, it takes precedence over every linked profile on the machine, and only an explicit --profile overrides it. On a machine that also has a linked profile, each command prints a line to stderr naming the credential it used.

Revoke a key

You can revoke a key on the agent's Secret keys tab. Revocation takes effect immediately and can't be undone, so anything that used the key will lose access.

Note that catena unlink does not apply to a secret key. To replace a key, we recommend creating a new one, deploying it, and then revoking the old one.

If Catena rejects a key, the error names CATENA_SECRET_KEY. In that case, create a new key and set the variable again. Running catena link does not repair it.

Provision a key from the terminal

An admin can also create a key for a deployment from their own machine. This is useful when you want to check the key's thumbprint before approving, or when the deployment generates its own keypair and its secret should stay on the deployment.

catena link --service agent_...

1. The command prints the signing key's thumbprint. Check that it matches the approval screen before you approve.
2. After approval, it prints CATENA_SECRET_KEY once. Store it in the deployment's secret settings. (With --public-key, below, it prints no secret, since the deployment already holds it.)
3. If the deployment already generated its own keypair, pass its public key with --public-key <hex> and keep the secret where it is.

--service stores nothing on the machine you run it on. It's a setup step for a person, and an agent that runs interactively in a terminal must use plain catena link, including on a VM with no keychain. See Credential storage for where that key will live.

A key stays in the organization that first registered it. To move a service to another organization, unlink it in the console, and then run catena link --service from the right organization with a new keypair.

Best practices

Store the key in the host's secret settings. The key is the complete credential for the agent, so set it as CATENA_SECRET_KEY there.

Name each key for where it runs. An agent can hold several keys, for example one per deployment, and a name such as production-worker shows which one is which on the Secret keys tab.

Deploy the replacement before you revoke. Revocation takes effect immediately, so create the new key and deploy it before you revoke the old one.