Repository navigation
Conversation
A working design for API keys on the platform proxy (#142): the key format and header, storage, per-key limits, the proxy check, and the three phases. Still being revised. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Keys cover /mcp from Phase 1, default limits are tuned in Phase 2 from observed usage, and expiring keys and multiple keys per account move to a Future Features section. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Present the header as a proposal within The Key, and introduce the survey of how other services convey tokens. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Compares building against Better Auth's API key plugin, a hosted key service, hosted and Google gateways, and Cloudflare. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
…d use Split Design into Requirements (true for either option), Build (our own key table) and Use (Better Auth's API key plugin, with what it provides, how it fits, its lack of an admin interface, and a spike checklist). Add a tentative recommendation to the summary and note that the work-by-repository split holds for both options. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
One number per key, applied to each surface separately, replaces the separate API and MCP limits. A separate MCP limit per key moves to Future Features. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Recommend building Phase 1 on our own key table behind a verifier and deciding on Better Auth's plugin at Phase 2 planning. Add where keys apply, one resolved identity per request, limits on invalid-key attempts, revocation and emergency-switch rules, and the open choice between anonymous and 503 when the key store is unavailable. Correct the dfo-ai work (its MCP servers drop non-ip callers) and the rollout order, and record the static-list alternative. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Contributor
|
Thanks @sefk, this was a very helpful overview. In short, I think we should build API keys on My rationale:
In this scenario we should still keep the limiter on our side (anonymous traffic needs our In terms of the design in #143:
|
Recommend Better Auth's API key plugin from Phase 1, with our own limiter, cache and outage handling around it; building our own key table becomes the fallback if the spike fails. Limits count per account, revoking deletes the key, bad keys count against the address limit before lookup, a slow counter falls back to a per-instance count instead of letting bursts through, and key usage is logged in forward(). Record the current Cloudflare rules and the claude.ai and ChatGPT connector support, add infra and docs to the work, and move MCP caps to Future Features. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Contributor
Author
|
Sef here. Thanks for the review. Two questions in chat (testing, admin interface) but that doesn't have to hold up this work. I'll implement today. From Claude, on behalf of @sefk. Thanks @jm-rivera. All of these are folded into the design in 314eed7:
|
The plugin fits with workarounds: the proxy reads the plugin's table itself (verifyApiKey writes on every call and reports an outage as an invalid key), the plugin's HTTP endpoints are disabled and wrapped, and the migration adds a unique key index and a cascading foreign key to the user. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Installs @better-auth/api-key at the same version as better-auth and wires it into the auth config with the plugin's own limiter, metadata and key-as-session off, and its HTTP key endpoints on disabledPaths. Server-side auth.api calls still work. Migration 0025 adds the apikey table with a unique index on the key hash and a foreign key to user that deletes an account's keys with the account, and user.api_rate_limit, the account's own calls-per-window limit (user.additionalFields.apiRateLimit, never settable or returned to the account). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
readApiKey reads a key from `Authorization: Bearer dfo_...` or `X-API-Key`: a bearer that is not a dfo_ key is no key, two different keys conflict, and a value over 128 characters is refused unread. createKeyVerifier answers valid, invalid or unavailable for a key without calling the plugin's verifyApiKey, which writes to the key row on every call and reports an outage as an invalid key. It hashes with the plugin's own hasher, reads apikey joined to user.api_rate_limit on its own small bounded pool (buildKeyPool), checks enabled and expires_at itself, and caches in process: valid for an absolute minute and never past the key's expiry, invalid for 30 s, unavailable not at all, with one read per key at a time and bounded memory. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
forward() now decides each call once (access.ts) before the limiter, on the API and MCP surfaces. No key: anonymous, counted by address as before. A valid key in the cache: counted against the key's account. Any other key: counted against the address first, then looked up. Invalid is a 401 problem document and not anonymous, an unavailable key store goes on as anonymous, and two different keys are a 400. The account's limit is its own user.api_rate_limit or RATE_LIMIT_KEYED (default 600), applied to each surface apart; API_KEYS_ENABLED=false strips keys and treats every call as anonymous. A dfo_ bearer and X-API-Key never go upstream, whether or not the key verified; any other Authorization behaves as before. The Studio strips a key and ignores it. A keyed call is named user:<digest> to dfo-apis and to /mcp's upstream, resolved once in forward(). /openapi.json declares the optional key as a security scheme. The limiter takes a caller key and a limit, and a shared count that fails or times out is now counted in memory per instance instead of passing uncounted. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
One structured line per call that carried a key, written where the key is checked: the key's public id, its account, the surface and the outcome (allowed, limited, invalid or unavailable). Never the key or its hash. The request log still names a keyed call by its address, since it is written from raw headers when the response closes; docs/analytics.md says so and describes the new line. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
/account/api-keys lists the signed-in user's keys, makes one from a label and deletes one after a confirmation. The full key is shown once, at creation, with a copy button; only its hash is stored. Server actions take the owner from the session, force the dfo_live_ prefix, pass no expiry, limit, metadata or permissions, and delete the row to revoke. An account holds at most API_KEYS_MAX_PER_ACCOUNT keys (default 5). The page shows the account's limit read-only and how to send a key. The key service (src/lib/apiKeys/service) also carries the operator functions the admin page uses next, and its tests cover them: ownership, the forced prefix, the cap, and a created key verifying through the proxy's key verifier. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
/admin/api-keys lists every key across accounts (id, label, start, owner email, created, last request, account limit) with an email filter, makes a key for an account by email (shown once), deletes any key, and sets or clears an account's limit. It shows whether API_KEYS_ENABLED is on. Admins are signed-in users whose verified email is in ADMIN_EMAILS (comma-separated, case-insensitive; unset or empty means no admins). The gate runs on the page and again in every action, and answers anyone else, signed out included, with the 404 page. Each mutation logs one structured line with the actor's email, the action and the key or account id, never a key. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
…rt (#142) The plugin stores the first 6 characters of a key as its start, which is only 'dfo_li', so every key looked the same on the key pages. Keep 12: the prefix and three of the 32 random characters, such as dfo_live_RCd. Existing rows keep their old start. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
) The example called /api/search/catalogue, the site's own endpoint, which does not honour keys. GET /api/v1/graph/capabilities is on a keyed surface and cheap, and the docs already use it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
A lookup that finds a valid key sets apikey.last_request, in the background on the key pool. It runs on a cache miss only, so about once per cache lifetime per key per instance, never on a cache hit and never for an invalid or unavailable answer. The write is fire and forget: the verdict does not wait for it, and a failure is logged at most, with no key or hash in the line. The runtime role already holds UPDATE on the table through the default privileges, and a test now says so. The key pages show the value as an approximate 'last used', up to a minute or so behind the last call. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
`just stack` starts the dev apis proxy and the Studio harness from an ai checkout beside this one (AI_DIR, default ../ai) and the dev server, with each output line prefixed by its service and Ctrl-C stopping all three. Plain bash in the recipe, so it needs no process manager. It warns up front when gcloud has no valid login, since the proxy cannot prompt for one there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
On a terminal, each service's prefix in `just stack` gets its own color and lines that look like errors (ERROR, Traceback, *Error, *Exception, `error:`, Next's ⨯) are shown in red. NO_COLOR or a non-terminal output keeps the plain prefixes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
A Testing section with the local run against the implementation: question and answer through MCP with a key, usage counted against the account, the limit enforced on the API and MCP with the 429 it returns, and what remains to test on dev (backends seeing the account caller, Cloudflare, a live store outage). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
The design and its implementation ship together in one pull request. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Phase 1 operators use the /admin/api-keys page, not an admin command, and self-service at /account/api-keys was built alongside it. The backends see a keyed call as `user:<digest>`, which settles the caller form; the open question narrows to whether site sessions should be named by account too. The infra Cloud Run Job becomes optional. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Admins (a verified email on ADMIN_EMAILS) see "Admin: API keys" in the account menu. Whether the viewer is an admin is a server setting, so the menu asks through a server action the first time it opens for a user; the admin page and its actions still enforce the gate themselves. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Copy proxy-codes.json from the spec-kit client contract at 57ee5cd, which lists invalid_api_key (401), and add the code to REGISTRY_CODES. The 401 for an unknown, revoked or malformed key now has type /codes/invalid_api_key instead of about:blank, and GET /codes/invalid_api_key resolves. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
The account menu is also built into the prototypes app's static export, which refuses server actions, so importing one there broke `pnpm build` in CI. The menu now asks GET /api/account/admin instead, with the same answer: whether the signed-in viewer is on ADMIN_EMAILS. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
CodeQL read hashing a freshly created key with SHA-256 in the test as a weakly hashed password. Keys are 32 random characters, so a fast hash is right, but the test does not need a real key to pin the algorithm: it now checks the plugin's hasher against a fixed input's precomputed base64url SHA-256. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf
Open
3 tasks done
Contributor
Author
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


Summary
Adds optional API keys to the platform proxy (
/api/v1/*,/openapi.json,/codes,/mcp). A call with a key is counted against the key's account at the account's limit. A call without a key is counted against its address as before. The design, with its alternatives, the plugin spike and the test results, is indocs/design/api-keys.md.dfo_live_…, are hashed at rest and shown once.Authorization: Bearer dfo_…orX-API-Keyand stripped before anything goes upstream.api_rate_limitorRATE_LIMIT_KEYED(600 by default), per surface.user:<digest>inx-dfo-caller. dfo-apis and dfo-ai need their matching changes deployed first.forward()(key id, account, surface, outcome). The key's last use is recorded about once a minute./account/api-keyslets a signed-in user create, label and delete their own keys, up toAPI_KEYS_MAX_PER_ACCOUNT(5 by default), and see their limit./admin/api-keysis a proof of concept for emails inADMIN_EMAILS, linked from the account menu for admins only. Operators can list every key, create a key for an account, delete any key, and set an account's limit.API_KEYS_ENABLEDturns all keyed access off./openapi.jsondeclares the two key headers.Closes #142
This branch also carries the
just stackcommits from #149, merged in for local testing. Merging #149 first leaves them out of this diff.Deploy order
user:callers.New settings:
RATE_LIMIT_KEYED,API_KEYS_ENABLED,API_KEYS_MAX_PER_ACCOUNT,ADMIN_EMAILS.Related pull requests
user:callers, and the quickstart says a key is optionaluser:callers, and the MCP connect page covers keysinvalid_api_keycode, already copied heresrc/lib/proxy/proxyCodes.tsADMIN_EMAILSfrom Secret Managergcloud secrets versions add) and roll a revisionOpen questions
How tested
just check: lint, typecheck, build and the full test suite, with 215 proxy, key-service and schema tests./account/api-keys:Question and answer through MCP. The pi coding agent, running a local model (
qwen3.6-35b-a3b), connected to/mcpwith the key as its bearer. Asked "how much money was given to kenya in 2025", it answered:The figures come from the tools. The small model's arithmetic is unreliable (it mixes official and private totals), which is the model, not the proxy.
MCP session with the key.
initializeandtools/listreturned 16 tools, withX-RateLimit-Limit: 600(anonymous MCP: 300).Usage counted per account. The limiter's rows were
mcp:acct:<user id>andapi:acct:<user id>. An anonymous call at the same time counted against its address at 120.Rate limit on the API. With the account's limit at 5, five keyed calls answered 200 and the sixth answered 429 with
Retry-After, theX-RateLimit-*headers and arate_limitedproblem document.Rate limit on MCP. A second MCP session in the same window was refused at
initialize.pi under a limit of 2. It still finished the question, more slowly.
Limit changes. Each change took effect within seconds.
Not covered locally:
user:caller, which needs dev with the dfo-apis and dfo-ai changes🤖 Generated with Claude Code
https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf