API Keys

Create, scope, and revoke API keys for the Catio MCP: permissions, workspaces, and how a key acts as you.

Long-lived credentials for the Catio MCP, for clients that cannot run the OAuth flow and for automation. To sign in with a browser instead, see MCP Setup. For keys that call the public Catio API, see API Authentication.

Creating a key

In the Catio console, go to Settings → API keys → New API key. You choose:

  • Name: what the key is for, for example "CI pipeline".
  • Expiry: how long the key lives, up to 365 days.
  • Permissions: what the key may do.
  • Workspaces: which workspaces the key can act in. Leave empty for every workspace you can access.

The secret is shown once, when the key is created. Copy it and store it safely: it cannot be recovered later.

Permissions

A key's permissions are one flat list. The console groups them for readability:

  • Integrations: read, create, update and delete integrations, for the public API.
  • Blueprints (recommendations): read, create and update recommendations.
  • Other: access:mcp for signing in to the Catio MCP, read:workspaces, read:requirements, read:stacks, and create:archie for asking Archie.

A key that signs in to the Catio MCP needs access:mcp plus at least one other permission.

A key acts as you

A key can never do more than you can. On every call, Catio checks the key's permissions against your live role: if you lose a role, the key loses the ability at the same time. If you are suspended, your keys stop working within about a minute.

Workspaces

Leave the workspace list empty and the key reaches every workspace you can access. Or list specific workspaces, and the key only acts in those. Every tool call names the workspace it works in through workspace_id; list_workspaces shows the workspaces the key can reach.

Revoking and regenerating

Revoke a key from the same console page. Revocation takes effect within about a minute, even if the key is still configured in a client. Regenerating issues a new secret. The old one keeps working until it is revoked or expires, so when rotating, create the new key first.

Next


Did this page help you?