You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The platform proxy (/api/v1/*, /mcp, /openapi.json) identifies callers by address only and gives each address one allowance (src/lib/proxy/forward.ts, src/lib/proxy/rateLimit.ts). Add API keys so a caller can be identified, given its own rate limit, and revoked.
Decided so far:
Anonymous access stays open, rate-limited by address as it is today.
A key carries its own rate limit.
Most of the work is in this repository. dfo-apis needs a small matching change to accept a keyed caller in x-dfo-caller.
The design and task breakdown will follow in a design doc, linked here once it exists.
The design is in docs/design/api-keys.md on #143, revised in 12eb7f1 after a design review with Codex.
Recommendation: build Phase 1 on a small key table of our own, behind a verifier that hides where keys are stored, and decide whether to adopt Better Auth's API key plugin when Phase 2 (self-service) is planned.
The review also changed the scope of the work:
dfo-ai needs a change as well as dfo-apis. Its MCP servers forward only ip:<digest> callers today, so the rollout order is dfo-apis, then dfo-ai, then the website.
The request log computes the caller separately from the proxy and needs the verified identity passed to it.
Attempts with invalid keys are limited per address before the key store is read.
Two questions are open before Phase 1 code: what the Cloudflare zone's rate rules are, and whether a call with an uncached key is served as anonymous or refused with a 503 when the key store is unavailable.
Implementation plan, following the design in docs/design/api-keys.md (#143):
Caller name. A keyed call is named to the backends as x-dfo-caller: user:<32 hex>. The hex is a keyed digest of the account id, the same shape as today's ip:<32 hex>, so allowances in dfo-apis count per account.
dfo-ai (feat/keyed-caller): the data, presentation and analysis clients pass user: callers on to dfo-apis instead of dropping them.
website spike: confirm @better-auth/api-key against the spike checklist in the design doc before any website code.
website (feat/api-keys): verifier with cache and outage handling, per-account limit, a fallback count when the shared limiter is slow, key usage logged in forward(), and the user: caller.
Key management: self-service key pages in the account menu, and a proof-of-concept admin interface.
Deploy order: dfo-apis, then dfo-ai, then the website.
Plugin and schema: @better-auth/api-key with its HTTP endpoints disabled. The apikey table has a unique key hash and a foreign key that deletes an account's keys with the account. user.api_rate_limit holds the account's limit.
Proxy: keys come from Authorization: Bearer dfo_… or X-API-Key and are stripped before forwarding.
Verifier: reads the plugin's table directly, with a cache. A store outage fails open as anonymous.
Limits: a key not in the cache is counted against its address before lookup. Valid keys count against the account's limit (RATE_LIMIT_KEYED by default).
Slow limiter: when the shared count is slow, each instance falls back to an in-memory count.
Caller and logging: the user: caller is sent to the backends, and key usage is logged from forward(). API_KEYS_ENABLED switches keys off, and /openapi.json declares both header schemes.
/account/api-keys: list, create (shown once) and delete your own keys, capped by API_KEYS_MAX_PER_ACCOUNT.
/admin/api-keys, a proof of concept for emails in ADMIN_EMAILS: list all keys, create for an account, delete any key, set or clear an account's limit. Every action is logged.
Tests: just check passes with 2,739 tests, including 215 proxy, key-service and schema tests.
Deploy order: dfo-apis, then dfo-ai, then website.
Still open:
invalid_api_key needs adding to the spec-kit proxy codes contract.
The site's request log still names keyed calls by address; per-key usage comes from the new usage line.
Already copied into #143. After it merges, update the spec-kit commit cited in src/lib/proxy/proxyCodes.ts
Open questions for @jm-rivera are listed in #143: how someone asks for a higher limit (likely a contact email address), and who else should be an admin.
Activity
sefk commentedon Nov 14, 2026
Comment written by Claude.
The design is in
docs/design/api-keys.mdon #143, revised in 12eb7f1 after a design review with Codex.Recommendation: build Phase 1 on a small key table of our own, behind a verifier that hides where keys are stored, and decide whether to adopt Better Auth's API key plugin when Phase 2 (self-service) is planned.
The review also changed the scope of the work:
ip:<digest>callers today, so the rollout order is dfo-apis, then dfo-ai, then the website.Two questions are open before Phase 1 code: what the Cloudflare zone's rate rules are, and whether a call with an uncached key is served as anonymous or refused with a 503 when the key store is unavailable.
docs(design): revise API keys design after a review with Codex (#142)
sefk commentedon Nov 16, 2026
From Claude Code, on behalf of @sefk.
Implementation plan, following the design in
docs/design/api-keys.md(#143):x-dfo-caller: user:<32 hex>. The hex is a keyed digest of the account id, the same shape as today'sip:<32 hex>, so allowances in dfo-apis count per account.feat/keyed-caller):resolve_calleracceptsuser:callers beside the website's shared secret.feat/keyed-caller): the data, presentation and analysis clients passuser:callers on to dfo-apis instead of dropping them.@better-auth/api-keyagainst the spike checklist in the design doc before any website code.feat/api-keys): verifier with cache and outage handling, per-account limit, a fallback count when the shared limiter is slow, key usage logged inforward(), and theuser:caller.Deploy order: dfo-apis, then dfo-ai, then the website.
sefk commentedon Nov 16, 2026
From Claude Code, on behalf of @sefk.
Implementation progress. Each branch passed a Codex review with no findings.
dfo-apis
feat/keyed-caller(fbff50ec)resolve_calleracceptsuser:<32 hex>beside the website's shared secret, as a new "account" caller kind.user:pin principals instead of rewriting them as raw secrets.dfo-ai
feat/keyed-caller(52808cb)user:callers to dfo-apis, as they forwardip:callers.website
feat/api-keys(9 commits, 14efb73..c13d579)@better-auth/api-keywith its HTTP endpoints disabled. Theapikeytable has a unique key hash and a foreign key that deletes an account's keys with the account.user.api_rate_limitholds the account's limit.Authorization: Bearer dfo_…orX-API-Keyand are stripped before forwarding.RATE_LIMIT_KEYEDby default).user:caller is sent to the backends, and key usage is logged fromforward().API_KEYS_ENABLEDswitches keys off, and/openapi.jsondeclares both header schemes./account/api-keys: list, create (shown once) and delete your own keys, capped byAPI_KEYS_MAX_PER_ACCOUNT./admin/api-keys, a proof of concept for emails inADMIN_EMAILS: list all keys, create for an account, delete any key, set or clear an account's limit. Every action is logged.just checkpasses with 2,739 tests, including 215 proxy, key-service and schema tests.Deploy order: dfo-apis, then dfo-ai, then website.
Still open:
invalid_api_keyneeds adding to the spec-kit proxy codes contract.feat(auth): add the API key plugin, table and account limit (#142)
feat(proxy): add the API key parser and the key verifier (#142)
feat(proxy): count calls with an API key against their account (#142)
feat(proxy): log API key usage from forward() (#142)
feat(account): add an API keys page to the account menu (#142)
feat(admin): add an API keys admin page, a proof of concept (#142)
fix(auth): keep the prefix and three random characters as a key's sta…
fix(account): use a keyed /api/v1 path in the API key curl example (#142
feat(proxy): record a key's last use when a lookup finds it (#142)
Merge the API keys implementation into the design branch (#142)
feat(account): link the API keys admin page from the account menu (#142)
sefk commentedon Nov 16, 2026
From Claude Code, on behalf of @sefk.
Pull requests for this phase, in the order they must merge and deploy:
user:caller until this is liveuser:callers, so keyed MCP use counts against dfo-ai itselfuser:callers, so it ships last. Merging #149 first keeps thejust stackcommits out of its difffeat(proxy): vendor the invalid_api_key code (#142)
fix(account): ask an API route whether the viewer is an admin (#142)
style(proxy): format access.ts with Prettier (#142)
test(auth): check the key hash with a known answer (#142)
docs(guide): say an API key is optional
docs(guide): say an API key is optional
sefk commentedon Nov 16, 2026
From Claude Code, on behalf of @sefk.
Updated merge order, now with the docs, spec-kit and infra pull requests:
user:callers; the quickstart says a key is optionaluser:caller until this is liveuser:callers; the MCP connect page covers keysuser:callers. Merging #149 first keeps thejust stackcommits out of its diffADMIN_EMAILSfrom Secret Managergcloud secrets versions addand roll a revisioninvalid_api_keycodesrc/lib/proxy/proxyCodes.tsOpen questions for @jm-rivera are listed in #143: how someone asks for a higher limit (likely a contact email address), and who else should be an admin.