Authentication
Every request needs a credential. The API under /v1 takes an API key or an OAuth access token from Korzy sign-in; the MCP server accepts either a key or sign-in with your Korzy account.
API keys
Create and revoke keys on your account page. A key is shown once, when you create it. Send it in the Authorization header on every request:
Authorization: Bearer korzy_…- Never put a key in a URL, query string, client-side code or a public repository.
- Use one key per application or environment, so you can revoke one without affecting the others.
- Revoked keys stop working within seconds.
- Use HTTPS only. If a key is ever sent over plain HTTP, treat it as exposed and revoke it.
Scopes
| Scope | Grants |
|---|---|
api:read | The API under /v1. |
mcp:read | The MCP server at /mcp. Its tools call the same /v1 operations, at the same credits. |
Choose scopes when you create a key. A request outside a key's scopes returns 403.
Only /v1 and /mcp are public. Paths under /api serve the Korzy map in the browser and return 404 with "code": "use_v1" to API keys and OAuth tokens.
Subscription
Keys work while your account has an active subscription. Without one, requests return 402 with "code": "subscription_required" and a link to choose a plan. Nothing is charged for these requests.
Sign-in for agents
MCP clients that support OAuth sign-in open a Korzy sign-in page the first time they connect, then store their own token. No API key is needed. See MCP server.
Failed attempts
Repeated failed authentication from one network is temporarily blocked with 429 and a Retry-After header. Check your key and wait before retrying.