Auth + keys
Bearer keys, account-scoped, revocable in one click.
The key
Keys look like edk_live_ plus 43 base62 characters. They are created on the Developer page, shown exactly once, and stored only as a sha256 hash plus the last 4 characters. Treat a key like a password: it authenticates your ACCOUNT, and scans it runs spend your account's credits.
Authorization: Bearer edk_live_...
Hosted MCP connections use browser OAuth instead. The MCP client renews that connection silently, so users do not copy API keys into Codex, Claude, Cursor, or VS Code.
What a key can do
| SCOPE | GRANTS |
|---|---|
research:read | query, snapshot, registry and reports. |
research:interpret | the natural-language proposer (POST /interpret). Included on MCP setup keys and metered separately: every call spends provider money. |
No write scopes exist in v1: definitions, alerts and report publishing stay in the app. The API is read-only by design while keys are new.
Where keys end
Keys terminate at the web layer. Each request mints a short-lived signed entitlement (the same one the app uses) and forwards your query to the research engine; the engine never sees or stores API keys. Revoking a key on the Developer page kills it immediately: revocation is a database row, not a cache.
Auth errors
| STATUS | CODE | MEANING |
|---|---|---|
| 401 | AUTH_REQUIRED | no Authorization header, or not a bearer key. |
| 401 | KEY_INVALID | the key is not recognized. |
| 401 | KEY_REVOKED | the key existed and was revoked. |
| 403 | SCOPE_MISSING | the key lacks the scope this endpoint needs. |
Transport errors use one envelope: {"error": message, "code": CODE}. Validation errors are different animals: see the grammar.