MCP Org API Keys
Org API keys are for trusted automation that needs MCP access without a human OAuth session.
MCP Org API Keys
Org API keys are for trusted automation that needs MCP access without a human OAuth session.
Use them for CI, internal admin bots, scheduled audits, and server-side clients. Do not place org API keys in browser code or public repositories.
Create A Key In The Dashboard
- Sign in as an admin.
- Open MCP Connections → Org API Keys.
- Click Create key.
- Enter a clear name, such as
Nightly docs auditor. - Choose a preset or switch to Custom.
- Optionally add allowed origins, one per line.
- Optionally set an expiration in UTC.
- Click Create key.
- Copy the raw
sk_org_...value immediately.
Kravos.ai stores only a hash. The raw key is shown once after creation or rotation.
Connect With A Header
Platform MCP accepts either header format:
Authorization: Bearer sk_org_...
or:
x-api-key: sk_org_...
If x-api-key is present, Kravos.ai tries it first. If bearer auth is present, Kravos.ai can authenticate either an OAuth access token or an API key.
Key Fields
| Field | Behavior |
|---|---|
name | Human-readable label. |
permissions | Required normal MCP permissions such as docs:read or sources:write. |
destructivePermissions | Separate delete, revoke, deactivate, and archive permissions. Default is empty. |
allowedOrigins | Optional exact web origins. Blank allows server-to-server clients from any origin. |
rateLimit | Optional requests-per-minute setting. If omitted by API creation, the domain default is 60. |
expiresAt | Optional ISO datetime. Expired keys cannot authenticate. |
The dashboard create form exposes name, preset/custom permissions, destructive permissions, allowed origins, and expiration. MCP API-key tools also support resourceGrants and rateLimit for advanced automation.
Allowed Origins
Allowed origins are normalized to URL origins. For example, this input:
https://app.example.com/dashboard
becomes:
https://app.example.com
Only http and https origins are accepted. If a key has allowed origins configured, MCP requests must include a matching Origin header. Server-to-server clients normally leave allowed origins blank.
Rotate A Key
Rotation replaces the stored hash on the same key record and returns a new raw key once.
- Create or prepare the replacement client configuration.
- In Org API Keys, click Rotate.
- Copy the new raw key.
- Update the MCP client.
- Confirm the key's Last used timestamp updates.
The old raw key stops working immediately after rotation.
Revoke A Key
Revoke a key when it should stop working permanently.
Revoked keys stay in audit/history records, but authentication rejects them. Revoked keys cannot be rotated from the dashboard route.
Manage Keys Through MCP
The Platform MCP server includes API-key management tools. Use them only from a key or OAuth connection that already has the required permission.
| Tool | Permission | Purpose |
|---|---|---|
list_api_keys | api_keys:read | List org and agent key metadata without hashes. |
get_api_key | api_keys:read | Read one key metadata record. |
create_api_key | api_keys:write | Create an org API key and return oneTimeRawKey. |
update_api_key | api_keys:write | Update permissions, grants, origins, rate limit, or expiry. |
rotate_api_key | api_keys:revoke | Rotate a key and return oneTimeRawKey. This is destructive. |
revoke_api_key | api_keys:revoke | Revoke a key. This is destructive. |
Agent API Keys And MCP
Existing agent API keys can authenticate to Platform MCP, but they are deliberately narrow.
| Agent key permission | MCP permissions it can map to |
|---|---|
chat | chat:write |
retrieve | sources:read, retrieval:read |
ingest | sources:write |
Agent API keys also keep safe agent-adjacent read permissions such as agent, media, skills, MCP server, voice, playground, and docs reads. They cannot get destructive permissions and can only target their own agent unless an explicit resource grant exists.
Audit Events
The dashboard lists recent MCP activity under MCP Connections → Recent Audit Events.
Key events include:
mcp.org_api_key.createmcp.org_api_key.updatemcp.org_api_key.rotatemcp.org_api_key.revokemcp.tool.callmcp.tool.deniedmcp.tool.destructive
Sensitive fields such as tokens, raw keys, secrets, headers, passwords, and private keys are redacted in the audit-event API response.
Related Docs
MCP Permissions
Pick a preset and understand destructive access before creating keys.
MCP Client Configs
Use an org key with Claude Desktop, Cursor, OpenCode, or a custom client.