Authentication
API keys, IP allowlists, scopes, and rotation.
Every request must carry a Bearer API key:
Authorization: Bearer ckf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeys are 32 url-safe characters prefixed with ckf_. Live mode only —
there is no separate test prefix.
Key lifecycle
| Action | Where | Notes |
|---|---|---|
| Generate | /dashboard/api/keys | Plaintext shown once. Max 5 active keys per workspace. |
| Revoke | /dashboard/api/keys | Immediate. Returns 401 KEY_REVOKED on any subsequent use. |
| Rotate | /dashboard/api/keys | Old key remains valid for 7 days. New key shown once. |
| Audit log | /dashboard/api/keys (history tab) | Every action recorded with caller IP. |
Lost keys cannot be recovered. Rotate instead.
IP allowlist
When generating or editing a key, supply a comma-separated CIDR list:
203.0.113.0/24, 198.51.100.42/32Requests from any other IP receive 403 IP_NOT_ALLOWED. Leave the list
empty for no restriction (not recommended for production).
The matched CIDR is checked against the real client IP — CiteFlow honors
X-Forwarded-For from its trusted edge only.
Scopes
API keys carry a fixed scope set. Scope mismatch returns 403 SCOPE_INSUFFICIENT. Today every key is issued with the full set:
audits:write—POST /audit,POST /audit/{id}:cancelaudits:read—GET /audit/{id}balance:read—GET /balancebilling:write—POST /billing/topupwebhooks:write—POST /webhooks/deliveries/{id}/replay
Per-scope restriction (e.g. read-only keys) lands later. The contract is stable; partners can pre-filter their request set today.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | Missing/empty Authorization header. |
| 401 | INVALID_API_KEY | Key not recognized. |
| 401 | KEY_REVOKED | Key was revoked. |
| 403 | IP_NOT_ALLOWED | Caller IP outside the allowlist. |
| 403 | SCOPE_INSUFFICIENT | Endpoint requires a scope the key lacks. |
Full table at Errors.
Storage on the server
CiteFlow only stores a SHA-256 hash of your key. The prefix (ckf_<6>)
is stored separately so the dashboard can show "Key ending in …a7f3"
without ever recovering plaintext.
Security recommendations
- Treat keys like passwords: never commit, never log.
- Always send over HTTPS — keys are not bound to a TLS session.
- Restrict CIDR ranges in production.
- Rotate every 90 days; the dashboard surfaces a rotation-due badge.
- Sign-in audit log lives in the dashboard — review monthly.