Guide · Security
JWT vs API Key Authentication
JWT and API keys both authenticate requests. When to use each—stateless vs stateful, revocation, and use cases.
Pick an identity pattern that covers users, services, and agents. Primary control: Authentication
Pick by revocation story, not fashion
API keys are long-lived secrets you look up (or hash-check) and can delete in one click. JWTs are signed claims valid until expiry—great for scale, awkward when you need an immediate kill switch. A B2B team revoked a leaked customer key in minutes; another team with 24-hour JWTs either waited or bolted on a blocklist (state again).
Decision shortcuts
Prefer API keys for machine-to-machine, partner integrations, and per-key quotas. Hash at rest, never ship in frontend JS, rotate on a schedule and on suspicion.
Prefer JWTs for user sessions and service-to-service passthrough where you want claims (sub, roles) without a DB hit every request. Keep access tokens short (≈15 min) plus refresh; treat long-lived JWTs as a footgun.
Many products use both: keys for tenant APIs, JWTs for the product UI.
Shared non-negotiables
HTTPS only. Never log raw keys or tokens. Rate limit per identity whether the credential is a key or a `sub` claim. APRF Authentication cares that public APIs have real AuthN and that secrets stay server-side—mechanism is secondary to custody and revocation.
If you're unsure, start with hashed API keys for B2B and short-lived JWTs for humans; add a denylist only when compromise response time demands it.
Next: Authentication
Open the related pillar specification for mandatory checks, artifacts, and pass conditions. Self-attest is optional.
Related
Frequently asked questions
- When should I use JWT vs API key?
- Use API keys for B2B or server-to-server when you need simple revocation. Use JWTs for user sessions when you need stateless auth and claims in the token.
- How do I revoke a JWT?
- JWTs are valid until expiry. To revoke: use short expiry (15 min) + refresh token, or add a blocklist (adds state). API keys are easier to revoke—just delete the key.
- Are API keys or JWTs more secure?
- Both can be secure. API keys are easier to revoke. JWTs are stateless but harder to revoke. Use short expiry for JWTs. Never put either in frontend code.