API Keys
Authentication is required for all data endpoints. Public endpoints like /health and /v1/public-stats do not require a key.
How Authentication Works
Every authenticated request must include your API key in the X-API-Key HTTP header. Keys are SHA-256 hashed before storage — the plaintext key is shown only once at creation time.
Header Format
X-API-Key: hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKey Lifecycle
| Action | Endpoint | Auth | Details |
|---|---|---|---|
| Create | POST /v1/api-keys | Clerk session | Returns plaintext key once. Store it securely. |
| List | GET /v1/api-keys | Clerk session | Shows key prefix, label, status, and usage count. |
| Validate | GET /v1/api-keys/validate | X-API-Key | Returns 200 if key is valid, 403 otherwise. |
| Revoke | DELETE /v1/api-keys/:id | Clerk session | Permanently deactivates the key. |
Security Best Practices
Never expose keys in client-side code
Use environment variables and server-side proxies. Never commit keys to version control.
Rotate keys periodically
Create a new key, update your applications, then revoke the old one.
Use descriptive labels
Label keys by environment or service (e.g., "prod-backend", "staging-analytics") for easy management.