The short answer
Create an API key in the app under Developers. Use the REST API at /api/v1, or the MCP server at /mcp, with Claude, Cursor or any client that can send a bearer token. Keys have read, write and approve scopes. Write actions only queue approval cards. Only the approve scope can make things go out.
The full reference is on Developers.
Keys
- Create keys at Developers in the app. A key starts with cosmo_live_ and is shown once.
- Up to 25 active keys per workspace.
- 120 requests a minute per key, REST and MCP combined.
Scopes
| Scope | Allows |
|---|---|
| read | Status, cards, plan, results and read-only tools |
| write | Queue approval cards (never acts), chat with Cosmo, and update what Cosmo remembers |
| approve | Approve or skip cards. Approving makes things go out, so only give this to code you trust |
Saying "yes" in a chat through the API never approves anything. Only the approve scope can.
Errors you might see
- 401: send your key as a bearer token (Authorization: Bearer cosmo_live_...).
- 403: the key doesn't have the scope that action needs.
- 402: write actions need an active trial or plan. Reads keep working.
Sign-in with OAuth isn't available yet, so connectors that can't send a bearer token won't work for now.
Still stuck?
Email roy@cosmocmo.com and tell us what you tried. We'll help.