API Keys
API keys are how your own backend services authenticate to Forge Core directly, without a user session — used for backend-to-backend calls like POST /api/core/auth/verify.
Key format
A generated key looks like fk_live_<20 base64url characters>. Send it on the x-forge-api-key header. Only a prefix and a hash are stored server-side — the full key is shown once, at creation time, and never again.
Lifecycle: active, disabled, revoked
A key has one of three statuses. Disable is a reversible pause; revoke is permanent.
| Status | Meaning | Reversible? |
|---|---|---|
active | Authenticates normally | — |
disabled | Paused by an admin — stops authenticating | Yes — re-enable it |
revoked | Permanently retired, kept as an audit record | No |
A revoked key can't be disabled or re-enabled — revocation is one-way by design. All three states are managed from the API Keys page (/dashboard/api-keys) or directly via /api/core/clients/:id/disable, /enable, and /revoke.
Expiration
A key can optionally be given an expiresAt date at creation time. Once past that date, /api/core/auth/verify rejects it the same way it rejects a disabled or revoked key.
Verifying a key server-side
Backend services call POST /api/core/auth/verify with the key on x-forge-api-key (and/or a Better Auth session bearer token) to check it in one round trip — this single endpoint validates status, expiry, and returns the resolved permissions.
curl -X POST http://localhost:3030/api/core/auth/verify \ -H "x-forge-api-key: fk_live_..."
Response is cached briefly
Verification results are cached for a short TTL to keep this a cheap, fast call for services that verify on every request. See documentation/API.md for the full response shape and error codes (missing_credentials, invalid_api_key, api_key_expired, invalid_session, user_banned).
Unused key flagging
The background worker (see /docs/worker) flags active keys that haven't been used in 90 days via a notification — it never auto-revokes. An idle key isn't necessarily compromised, so the decision to disable or revoke it is left to an admin.
Related permissions
api-keys.view— list and inspect keysapi-keys.create— issue a new keyapi-keys.revoke— revoke, disable, or re-enable a key