Skip to main content

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 via API_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 the Authorization HTTP header as a Bearer token:
Missing headers, malformed tokens, unknown keys, or revoked keys return 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: 60 requests 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 (300 failed attempts per hour by default, configurable via API_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.