API keys
An API key is how an AI tool (Claude Desktop, Claude Code, Cursor, or any MCP-compatible client) proves it is allowed to work with your portal. You manage every key at /admin/settings/api-keys.
Two kinds of keys, one page
The page shows both kinds of keys your portal can use, because they are easy to mix up:
- MCP server keys let an outside AI tool call into your portal: read clients and billing, clock time, draft and send quotes. These are the keys this page creates and revokes. They only work once the MCP server is switched on at /admin/settings/mcp. Full picture in MCP server (AI agents).
- The AI provider key points the other direction: your portal calling out to a cloud AI (OpenAI, Anthropic, Gemini, xAI) to power the customer chat widget and the admin assistant. This page shows its status (provider, model, and the last four characters of the key), but you add or rotate it on Settings → Support Chat. Self-hosted setups manage theirs on the Self-Hosted AI page instead.
Creating an MCP key
Open /admin/settings/api-keys/create (the MCP Server page's Setup tab links straight here with an MCP preset). Creating a key takes three decisions:
- Name it. Pick a label you'll recognize later, ideally naming the device or person, like "MCP Server (Albert's iPhone)". If you'll have more than one key, this is what tells them apart in the audit log.
- Confirm the organization. Every key is bound to your organization only. It can never see other organizations or anything outside your account.
- Pick write groups. Read access is always on; write access is entirely opt-in.
Read access is always on
Every key can read client profiles, health scores, projects, billing snapshots, notifications, and the activity log. The search and identity tools (whoami, find_client, find_project, find_active_session, find_recent) are always available too. There is no partial-read option: you either trust the agent with your data or you don't create a key.
Write access is off by default
Writes are split into groups so you can issue narrow keys, for example a "time tracking only" key for a worker's phone that can never touch billing:
| Group | What it unlocks |
|---|---|
| Time tracking | Clock in and out, session notes, billable flags, time corrections. |
| Clients | Create, update, archive, and restore client records. Archiving needs a spoken two-step confirmation. |
| Projects | Create and update projects, mark them complete, attach service plans. |
| Billing & comms | Send invoices, quotes, and contracts, mark payments received, request approvals. Every send needs a two-step confirmation, at any amount, and supports a dry-run preview. |
| Calendar | Add calendar events. |
| Settings | Change a curated set of org settings. Money and tax settings need a two-step confirmation. |
| Team | Invite an admin teammate (owner-only, two-step confirmation). Viewing the team list is read-only and needs no write group. |
Groups that include a destructive or money-moving tool are flagged destructive on the form so you know what you're granting.
Copy the key immediately
After you click Create MCP Key, the full key (it starts with ctsp_live_) is shown once, in a banner back on the API Keys page. Copy it right away and paste it into your AI client's configuration. After that, the portal only ever shows the key's short prefix. If you lose a key, revoke it and create a new one; there is no way to view it again.
Managing and revoking keys
The Your Keys table at /admin/settings/api-keys lists every key with its label, prefix, status, last-used time, and creation date. The last-used column is the quickest way to spot a key that's gone stale or one that's suddenly busy when it shouldn't be.
Click Revoke to kill a key instantly. Revoked keys stay in the list, marked Revoked, so the history is never lost. Revoking one key doesn't touch the others, which is exactly why per-device keys beat one shared key.
If two phones share a key, revoking it kicks both off, and the audit log can't tell you which one did what. A key per device costs nothing and keeps both problems away.
Safety nets that stay on regardless
No matter which write groups a key has, these limits always apply:
- A per-recipient email cap: at most 30 emails to the same address in 24 hours.
- Archiving a client requires a two-step confirmation token.
- Invoice, quote, and contract sends all support a dry-run preview and require a two-step confirmation on every send, regardless of amount.
- Every call, success or failure, is written to the audit log: which key, which tool, when, from what IP.
If keys aren't working
- Every request rejected? Check that the MCP server is enabled at /admin/settings/mcp. With the server off, no key works, which also means a leaked key is harmless while the toggle is off.
- "Insufficient permissions" errors? The key is missing the write group for that tool. Revoke it and create a new key with the right groups checked.