Core API

Authentication and API key handling for Contro1

Secure your Contro1 integrations with environment-based API keys, role-aware routing, and clear ownership boundaries.

Authentication is simple on the wire, but safe key storage and route ownership are what make the integration production-ready.

Key takeaways

An agent authenticates as itself with an Agent Credential, a key bound to one agent. Identity comes from the credential, never from a request body.
An MCP client authenticates as the person who approved it, through OAuth, and can do only what that person can.
An agent on a computer uses a key held by the Contro1 service there, which never leaves the machine.
Webhook signing uses a shared secret distinct from any credential.

Three credentials, by where the caller runs

What a credential may do depends on what it means if somebody else gets hold of it. That is why there are three, and why they are not interchangeable.

Credential	Who uses it	Acts as	How it is sent
Agent Credential (cc_live_...)	An agent in your own code: LangGraph, Mastra, a worker	The agent it is bound to	Authorization: Bearer <credential>
OAuth token from an MCP approval	Grok, Claude, ChatGPT, Cursor, Codex	The person who approved it, and nothing more	The MCP client handles it
Key held by the Contro1 service	Claude Code, OpenClaw, NanoClaw on a computer	The agent, with a key that cannot be exported	The local service signs every call (DPoP); the agent sends none

Connect an agent: which one you need

Base authentication pattern

Create an Agent Credential under Settings, API keys, Create Agent Credential, and choose the agent it belongs to. A key with no agent and no scopes is a legacy organization key: it still works for approval requests, and the Action API refuses it with SCOPE_UPGRADE_REQUIRED.

headers.txt

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Security rules

Store API keys in server-side environment variables, never in browser code.
Rotate keys when ownership changes.
Separate test and production keys.
Use webhook secrets for callback verification.

Team ownership

API authentication proves the app can create requests, while required roles and operator permissions decide who is allowed to answer them.

API keys can also carry default routing. When a request response shows routing_source: "api_key_default", the request used the routing configured on that key in Settings -> APIs & Webhooks. A request-level routing field can override the default when your integration needs a different team or role.

Frequently asked questions

Can different teams use different keys?

Yes. Many organizations separate environments, internal tools, or business domains with different keys and routing policies.

What happens if a key leaks?

Rotate immediately in Contro1 settings. Requests created with the old key continue to callback normally, but no new requests can be created with it.

How do I test safely?

Use a cc_test_ prefixed key against a staging workspace. Callbacks are real HTTP but operator decisions are isolated from production queues.