# Security

Catena enforces each agent's policy and checks the agent's credentials on every
signed request. If you need to stop an agent, you can revoke its access at any
time, and the change will take effect immediately.

## Custody

When you create an account, your sign-in method (such as a passkey or Google) is
used to create cryptographic signing authority over your funds. Catena cannot
access or move funds in or out of your account on its own. **Money moves only
when you, or agents and people you approved, authorize it.**

When you link an agent with permission to send from an account, the agent's
identity includes signing material that is kept on the agent's machine. The
agent then becomes an approved signer on your account, constrained by the
policies you set, and you can change or revoke that permission at any time. We
describe this design in more detail in
[Binding policy to money](https://catena.com/blog/binding-policy-to-money).

## Agent credentials

Each linked machine and each secret key has its own P-256 key. You can think of
this key as the agent's password, with one difference: the key stays on the
client, and the CLI and the SDK use it to sign each request. A signed request
carries no session token.

The CLI stores the key in the OS keychain where one exists (e.g., the macOS
Keychain). Otherwise, it stores the key in a file that only your user can read.
See [Credential storage](https://docs.catena.com/connect/credentials.md) for more details.

We look up the agent's link on every signed request, so unlinking a machine or
revoking a key will take effect immediately.

> [!NOTE] **Secret keys are shown once**
>
> Catena shows a [secret key](https://docs.catena.com/connect/secret-keys.md) once, when it is created.
> Only admins can create or revoke secret keys, and only from a signed-in
> console session.

## Policy and approvals

We enforce the policy, and an agent cannot raise its own limits. However, an
agent can [ask for a temporary increase](https://docs.catena.com/recipes/raise-a-limit.md), which an admin
will approve or deny.

The following protections apply to every payment:

- An approved payment is signed, submitted, and checked before money moves. See
  [Approval and execution](https://docs.catena.com/approvals.md#approval-and-execution).
- Before the CLI or the SDK signs a payment, it checks the payment against the
  action you submitted. It will refuse to sign a payment that would not pay the
  amount you asked for.
- An MCP connection holds no signing key, so each payment it submits will wait
  for an admin to approve and sign it.
- An x402 or MPP endpoint is paid only at an address that is already a saved
  counterparty. Adding a counterparty is its own request, which the policy
  evaluates.

## People and roles

Each person on your team has a role. Below is what each role can do.

| Role     | Description                                                                  |
| -------- | ---------------------------------------------------------------------------- |
| Viewer   | Viewers can read.                                                            |
| Operator | Operators can also work with agents and counterparties.                      |
| Admin    | Only admins can move money, approve, write policies, and manage secret keys. |

See [Team and roles](https://docs.catena.com/team.md) for the full list. In addition, console sessions end
after 15 minutes without activity (the console warns you during the last
minute).

## Records

Each action by a person or an agent appears in **Activity**. Admins can also
export the agent money activity and operational exceptions reports as CSV for a
date range.

## Revoke access

You can revoke access at several levels, depending on what you need to stop:

| To stop             | Do this                                                                       |
| ------------------- | ----------------------------------------------------------------------------- |
| One machine         | Run `catena unlink` on it, or unlink it from the agent's page in the console. |
| One deployment      | Revoke its secret key on the agent's **Secret keys** tab.                     |
| An agent's spending | Remove or change its policy. An agent with no policy can do nothing.          |
| One MCP connector   | Unlink it in the console, and remove it in the app.                           |

## CLI telemetry

When the CLI fails before a request reaches the Catena API (for example, on a
keychain error), it may send one report. The report contains a fixed failure
code, the CLI version, the operating system family, the Node.js major version,
and a schema version. It doesn't contain command arguments, error text, paths,
URLs, credentials, or user or organization identifiers.

If you'd like to turn reporting off, set `DO_NOT_TRACK=1`.

## Report a vulnerability

If you believe you've found a security issue, please follow the policy at
[api.catena.com/.well-known/security.txt](https://api.catena.com/.well-known/security.txt).

## Related

- [Credential storage](https://docs.catena.com/connect/credentials.md): Where the CLI keeps an agent's signing key on each kind of host, and which credential mode to use when there's no keychain.
- [Handle approvals](https://docs.catena.com/approvals.md): Learn what goes to the approvals queue, who can approve, when requests expire, and what happens between an approval and a completed payment.
- [Team and roles](https://docs.catena.com/team.md): The three roles in a Catena organization, what each one can do, and how operators and admins divide the work.