Back to Docs

Documentation

API Keys

All tiers

Manage API keys from your dashboard. Calls to tier-gated endpoints require a key in the Authorization: Bearer ... header. Public read endpoints (entity lists, details, scorecards, methodology) need no key.

Creating a key

On /dashboard/keys, click Create new key. Give it a label that describes where the key will live (e.g. production-api, staging-batch-job, ci-tests). Labels are required and unique per-account — they help when you have multiple keys and need to rotate one.

The full key value (e.g. verdict_pk_abc123def456...) is shown once at creation. Copy it immediately to your secrets manager (env vars, AWS Secrets Manager, Doppler, etc.). Keys cannot be retrieved later — only the prefix and suffix are stored for display.

Storage best practices

  • Never commit keys to git. Use .env + .gitignore, or a dedicated secrets manager.
  • Don't expose keys in client-side code. Public reads work from the browser with no key; for tier-gated data in a browser app, proxy through your backend so the key stays server-side.
  • One key per environment. Don't share a "production" key across staging — that's how staging mistakes nuke production budgets.
  • Rotate every 90 days. Create the new key, deploy it, then revoke the old. Zero downtime.

Rotation

To rotate a key without downtime: create a new key with a new label, deploy it to production, verify traffic is using the new key (the dashboard's Usage page shows per-key request counts), then revoke the old key.

Revocation

Click Revoke next to a key on /dashboard/keys, then confirm. Revoking disables the key: every subsequent request returns 401 with error code disabled_key, and propagation is instant. A disabled key is reversible, so you can re-enable it from /dashboard/keys. Permanent removal is the separate Delete action, which appears only on a disabled key and cannot be undone.

If you suspect a key is leaked

Revoke immediately, then create a replacement. Check the Usage page for any unexpected request volume in the last 30 days. Email support@verdict.finance if you need a usage audit.

Key limits

Each account can have up to 5 active keys. This headroom lets you separate environments (production / staging / CI) and rotate without downtime. Per-tier key limits are on the roadmap; until they ship, all tiers share the 5-key cap. Reach out to support@verdict.finance if you need a higher cap before then.

Authentication header format

Every authenticated API call must include the header:

Authorization: Bearer verdict_pk_yourkeyhere

Missing or malformed header returns 401 Unauthorized. See Errors & Troubleshooting for the full error-response shape.