How to run a headless agent or CI job with a CoreSpeed API key

A headless agent or CI job authenticates to https://api.corespeed.io/mcp with an API key instead of a browser sign-in. A member key (sk-cs-) acts as you. An agent key (sk-csa-) acts as an agent principal and reaches the organization's shared connections only. Send it as Authorization: Bearer, read it from an environment variable, and cap its monthly spend.

Which key should a headless job use?

An agent is the organization's third principal kind. Any member can create one in Dashboard → Settings or with manage__agents_create and becomes its owner: the member who answers for it and who, with org admins, may manage it. Ownership is accountability. The agent inherits neither the owner's connections nor the owner's role.

Give unattended work an agent key. The activity trail then names the agent. Suspending it stops every request with 403 agent_suspended while its keys stay intact. Retiring it revokes the keys for good while the record survives for attribution. The full model is on the Authentication page.

How do you create the key?

1. Member key: open Dashboard → API keys and create one, or run cs keys create production from the CLI, which prints the sk-cs- secret once. A signed-in agent can also mint one with the manage__keys_* tools.
2. Agent key: create the agent first, then mint a key for it from the dashboard or with manage__agents_key_create. Only the owner or an org admin can.
3. Set a monthly spend cap in credits on the key. Keys belong to an organization, live until revoked, rotated or expired, and are per environment.

How do you put the key into the client?

4. Store the key in an environment variable named CORESPEED_API_KEY wherever the job runs. Let the server entry read the variable, so the key itself is never written into a config file:

# Claude Code: single quotes, so the entry stores the variable, not the key
claude mcp add corespeed https://api.corespeed.io/mcp --transport http --scope user \
  --header 'Authorization: Bearer ${CORESPEED_API_KEY}'
# Codex
codex mcp add corespeed --url https://api.corespeed.io/mcp --bearer-token-env-var CORESPEED_API_KEY

A client that reads an mcpServers map takes the same entry as the browser form plus a headers object whose Authorization value is Bearer followed by the key. The header forms are Authorization: Bearer for any credential and x-api-key for keys only.

Never print, log or commit the key. In Claude Code, claude mcp list hides headers; claude mcp get prints them, key included, so avoid it in transcripts. If the machine already had a browser entry for corespeed, remove it first with claude mcp remove corespeed --scope user or codex mcp remove corespeed. Duplicate registrations collide on tool names.

How do you verify a key works?

5. Call memory__list_memory. It is free, and a 200 without isError proves the key authenticates.
6. Expect manage__whoami to refuse. It answers 200 with isError: true and code jwt_session_required, because manage__whoami, manage__keys_*, manage__agents_*, manage__accounts_* and manage__switch_org run only under a member session. Those tools still appear in tools/list for a key. Presence is not permission. manage__remote_list runs for anyone.

A 401 means the key is unknown, revoked or expired; replace it and do not retry. A 403 means the key's agent is suspended; resume the agent, since a new key would be refused the same way. A 503 means the key authority was unreachable and CoreSpeed failed closed rather than trust an unverified key; retry with backoff.

What happens when the cap is reached?

Two boundaries stop metered calls before a tool runs, and both arrive on /mcp as 200 with isError: true:

• key_spend_limit_exceeded: this key's monthly cap is reached. Metered calls with it stop until the month rolls over or the cap is raised.
• payment_required: the organization wallet is past its billing threshold. Adding credit clears it.

Through either hold, discovery (tools/list), account reads and key management keep working. Caps are request-boundary guardrails rather than reservations, so an action already in flight can finish above the remaining amount. Neither code clears on retry. The retry rules for every code are in Error handling; the ledger and caps are on the Billing page.

Branch on result.isError before you read any result. Treating a 200 as success is the most common integration bug.

Every call with a key is attributed through the key's owning identity in Dashboard → Activity: the member for an sk-cs- key, the agent for an sk-csa- key.

FAQ

Can the cs CLI take the API key? No. The CLI runs under a browser sign-in and takes no key. Mint the key once with cs keys create and send it directly from the job; the CLI is not part of the job. See the CLI page.

Does an agent key reach my private Notion? No. An agent principal reaches the organization's shared connections only. Share the connection, or use a member key.

Should I rotate the key when a tool answers needs_reauth? No. One connected account needs a member to reauthorize it in Dashboard → Connectors. The key is fine.

How do I rotate a key? cs keys rotate with the key id, or Dashboard → API keys. Update the environment variable where the job runs.