What is an agent identity (and why not just an API key)?
An agent identity is a principal of its own, with an id, keys, an owner who answers for it, and reach limited to shared connections. A personal API key acts as you.
An agent identity is a principal of its own inside an organization: its own id, its own keys, an owner who answers for it, and reach limited to the organization's shared connections. A personal API key acts as the member who created it. An agent identity acts as itself, and can be suspended or retired without touching anyone's account.
Why does a personal API key fall short for an unattended agent?
A member key, the sk-cs- kind, acts as you. Every call it makes reaches every connection you can reach, including the private ones: your Gmail, your personal X handle, the Notion workspace you connected for yourself. The activity trail attributes those calls to you. An approval card for a held write goes to you.
That is right for a coding agent on your laptop. It is wrong for a nightly job you operate on a server, a support bot built on an SDK, or any process that keeps running when you are not watching. Three problems follow.
- Reach: the job can act through your private accounts, which nobody intended.
- Attribution: the trail says you did it, and you cannot tell the job's actions from your own.
- Lifecycle: the day you leave the organization or rotate your key, the job stops, with no record of its own.
Service accounts solved the same problem for cloud infrastructure. An agent identity is the same idea for agents.
How does an agent principal work?
A CoreSpeed organization has member principals and agent principals. Any member can create an agent, in Dashboard → Settings or with the manage__agents_create tool, and becomes its owner. The owner is the member who answers for the agent and who, together with org admins, may manage it.
Ownership is accountability, not permission. The agent inherits neither the owner's connections nor the owner's role. It reaches the organization's shared connections only, never a member's private ones. If the job needs Slack, an admin connects Slack as a shared connection or installs the workspace integration. The agent then sees slack__post_message in its tools/list, and the call is attributed to the agent.
The agent's credentials are agent keys, prefixed sk-csa-, minted by the owner or an org admin. A headless client sends one in the same place a member key would go:
{
"mcpServers": {
"corespeed": {
"type": "http",
"url": "https://api.corespeed.io/mcp",
"headers": { "Authorization": "Bearer sk-csa-..." }
}
}
}Read the key from an environment variable such as CORESPEED_API_KEY rather than writing it into the config file. Like a member key, an agent key belongs to the organization, lives until revoked, rotated or expired, is issued per environment, and can carry a monthly spend cap in credits.
Which credential should each agent use?
| Credential | Who it is | Reaches | Use it for |
|---|---|---|---|
| Browser sign-in (MCP OAuth token) | You, a member | Your private connections and the org's shared ones | Claude Code, Codex, Cursor, claude.ai, ChatGPT on your own machine |
sk-cs- member key | The member who created it; acts as you | Same as browser sign-in | CI and headless clients that act for you |
sk-csa- agent key | An agent principal | Shared connections only | Unattended jobs, bots, anything that acts as itself |
| Session JWT | Your signed-in session | What the cs CLI and dashboard need | The CLI and the dashboard |
All four go in Authorization: Bearer; the two keys also work as x-api-key. Session-gated tools such as manage__keys_*, manage__agents_* and manage__whoami run only under a member session; an API key gets 200 with isError: true and the code jwt_session_required. The authentication docs list every rule.
What happens when you suspend or retire an agent?
Suspend is reversible. The agent's calls answer 403 agent_suspended, its keys stay intact, and lifting the suspension restores it. Use it when a job misbehaves and you want it stopped now without losing anything.
Retire is terminal. The record survives for attribution, so the trail still says which agent did what. Its keys are revoked, and any further call answers 401 invalid_api_key. Use it when the job is decommissioned.
Neither action touches the owner's account, the owner's keys or the shared connections the agent used. That separation is the point of a principal of its own.
How do approvals and the trail treat an agent?
Smart Approval judges an agent's writes the same way it judges a member's. When a call is held, the card goes to the owner of the agent. The agent cannot approve its own action. Every call the agent makes lands in Dashboard → Activity attributed to the agent, with the outcome, the surface and the time; see Activity and audit. Spend follows the same path: the key's monthly cap and the organization's wallet both apply, and every charge lands in the one ledger.
FAQ
Can an agent reach my private Gmail or Notion?
No. An agent principal reaches shared connections only. If the job needs an app, connect that app as shared, or install the organization integration where the vendor offers one.
Who can create an agent?
Any member. The creator becomes the owner and answers for it. Org admins can also manage it.
Does the agent inherit the owner's admin role?
No. Ownership is accountability. The agent gets no role and no connections from its owner.
What is the difference between suspend and retire?
Suspend is reversible and keeps the keys; calls answer 403 agent_suspended. Retire revokes the keys for good; calls answer 401 invalid_api_key, and the record stays for attribution.