Authentication
Authenticate with Bearer API keys
Create server-side keys, rotate them safely, and handle per-key rate limits without exposing secrets to browsers or mobile clients.
RESTBearer authJSON responses
Auth header
Authorization: Bearer $AIFACESWAP_API_KEY{
"x-ratelimit-limit": "60",
"x-ratelimit-remaining": "59",
"x-ratelimit-reset": "1760000000"
}Server-side only. Keep API keys out of client bundles.
Authentication
Every request must send an API key in the Authorization header.
Authorization: Bearer $AIFACESWAP_API_KEYKey lifecycle
- Create a key from /dashboard/api-keys. The full secret is shown only once. We store an HMAC of the key, not the key itself — lost keys cannot be recovered, only revoked and replaced.
- Revoke a key from the same page. Revocation is immediate — all in-flight requests with the revoked key start returning
invalid_api_keywithin seconds. - Rotate by creating a new key, deploying it, then revoking the old one. We do not surface separate webhook secrets — the API key itself signs outbound webhooks, so rotation = revoke + recreate.
Security tips
- Never embed the key in client-side code, mobile apps, or browser bundles.
- Store the key in a server-side secret store (env var, Vault, KMS) — not in your repo.
- Use one key per environment and one per integration so you can revoke narrowly.
- Quotas are per-key, not per-user. Two keys on the same account get independent limits.
Rate limits
Limits are enforced per API key. Counter writes are best-effort under burst; credits still independently bound spend.
| Cap | Value | Failure code |
|---|---|---|
| Per-minute | 60 req / min | rate_limited |
| Daily (UTC) | 10,000 req / day | rate_limited_daily |
| Concurrent swaps | 10 | rate_limited_concurrent |
Response headers
x-ratelimit-limit— per-minute cap.x-ratelimit-remaining— requests left in the current window.x-ratelimit-reset— unix epoch seconds when the window resets.Retry-After— seconds to wait on every 429 response.