API Keys

Every agent, script, and tool that talks to Kiomon — MCP servers, the OpenAI-compatible API, REST calls — authenticates with an API key.

Creating a key

1. Open the dashboard → Settings → API Keys.
2. Click Generate Key (optionally give it a label, e.g. cursor, n8n, ci-scripts).
3. Copy the key immediately — it’s shown only once at creation and stored securely, so it can’t be recovered later.

Using a key

Surface	Where the key goes
MCP server	KIOMON_TOKEN env var (or --token)
OpenAI-compatible API	Authorization: Bearer <key>
REST API	Authorization: Bearer <key>
Extension	Automatic — uses your dashboard session cookie instead

Finding your keys

GET /api/keys lists your keys with their id, prefix (first 16 chars, for identification), label, tier, and created_at. You’ll never see the full key again — only the prefix for recognition.

Managing keys

• Security best practice — one key per tool, labeled, so you can revoke a single access path without breaking others.
• Revoke — delete the key (the DELETE endpoint or the dashboard). Revocation is immediate: any client using the key starts getting 401s.
• Create more — Free accounts can hold 1 key; Pro up to 10. The API enforces the cap with a 402 upgrade response.

Rotating a key

1. Create a new key.
2. Update your MCP configs / scripts to the new key.
3. Delete the old key.

Because both keys work until the old one is deleted, rotation is zero-downtime.

Troubleshooting

Symptom	Cause
401 on every call	Key wrong, revoked, or regenerated since your config was written
402 on key creation	At the plan’s key limit — upgrade or delete an unused key
MCP starts but says “No API token”	KIOMON_TOKEN isn’t set in the client’s env config