Authentication
Public API (/api/v1/*) and remote MCP (/api/mcp) requests authenticate with Developer API keys.
Create an API key
Open Settings → API & MCP in the web app to create a key. Both Free and Premium accounts can hold up to 5 active API keys (overrideable viaAPI_MAX_ACTIVE_KEYS on self-hosted deployments).
API keys use this shape:
- Only the SHA-256 hash of the full API key is stored on the server; the plaintext secret is displayed once at creation time.
- Keys never expire automatically and remain valid until you revoke them (or delete your account).
Send the key
Send the key in theAuthorization HTTP header as a Bearer token:
401 (authentication_required or invalid_api_key).
Scopes
Each API key carries scopes that bound what it can do:read is always present. By default a new key is granted both read and write. To create a read-only key — recommended for analysis agents that should never modify data — select Read only in Settings → API & MCP (which sends "scopes": ["read"]).
A write operation attempted with a read-only key returns 403 insufficient_scope. Note that duplicate detection (/api/v1/analytics/duplicates) and optimization candidates (/api/v1/analytics/optimizations) additionally require Lifetime Premium (403 premium_required on Free accounts).
Rate and failed-authentication limits
- Authenticated requests:
60requests per minute per account by default (API_RATE_LIMIT_PER_MINUTE), shared across all active keys for that user on both Free and Premium plans. - Failed authentication attempts: invalid API key attempts are rate-limited per client identity (
300failed attempts per hour by default, configurable viaAPI_FAILED_AUTH_RATE_LIMIT_PER_HOUR).
Security notes
- Do not expose API keys in untrusted browser code or public repositories.
- Treat API keys like passwords.
- Use one dedicated key per integration or MCP client so you can revoke it independently.
- Rotate keys immediately if a secret may have been copied into logs or shared transcripts.