Core Code
Core Code Modern Dev Handbook

API Keys

API keys are simple, common, and risky. Learn where they fit, how to store them, and how to rotate safely.
On this page

What an API key is

An API key is a shared secret that identifies a client application. It's easy to implement and works well for server-to-server integrations. It's weak for end-user scenarios unless combined with stronger auth.

When API keys make sense

  • Internal services and trusted integrations
  • Partner integrations where you can rotate keys
  • Metering, rate limiting, and basic access control

When API keys are not enough

  • End-user authentication (you need user identity + consent)
  • Public clients (mobile apps, SPAs) where secrets can be extracted
  • High-security scenarios (use OAuth 2.0, JWT with proper flows, etc.)

Where to put the key

Prefer the Authorization header. Avoid query parameters because URLs leak into logs, analytics, referrers, and caches.

Example: Authorization header

GET /api/reports/daily
Authorization: ApiKey YOUR_KEY_HERE
Accept: application/json

Example: cURL

curl -H "Authorization: ApiKey YOUR_KEY_HERE" 
     -H "Accept: application/json" 
     https://example.com/api/reports/daily

Key storage rules

  • Never hardcode keys in frontend JavaScript
  • Store keys in environment variables or server config
  • Mask keys in logs (log only the last 4 chars)
  • Use least-privilege scopes if you support them

Rotation strategy

Keys should be rotatable without downtime. A safe approach is dual keys: allow both old and new for a window, then revoke the old key. Track created_at, last_used_at, and optionally per-key rate limits.

Common mistakes

  • Putting keys in query string: ?api_key=...
  • Never rotating keys (one leak = permanent breach)
  • Sharing the same key across multiple clients/environments

Checklist

  • Keys are only used in server-to-server or trusted client contexts
  • Authorization header is used (not query param)
  • Rotation and revocation exist
  • Logs never expose full keys
Basic Authentication →