Skip to content

Add API keys to the platform proxy #142

Open

Description

@sefk

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.

Activity

  1. self-assigned this
    on Nov 13, 2026
  2. added
    P1Major: a feature is broken or data is wrong, with a workaround. Fix this cycle.
    on Nov 13, 2026
  3. sefk commented on Nov 14, 2026

    @sefk
    ContributorAuthor

    Comment written by Claude.

    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.

  4. sefk commented on Nov 16, 2026

    @sefk
    ContributorAuthor

    From Claude Code, on behalf of @sefk.

    Implementation plan, following the design in docs/design/api-keys.md (#143):

    1. 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.
    2. dfo-apis (feat/keyed-caller): resolve_caller accepts user: callers beside the website's shared secret.
    3. dfo-ai (feat/keyed-caller): the data, presentation and analysis clients pass user: callers on to dfo-apis instead of dropping them.
    4. website spike: confirm @better-auth/api-key against the spike checklist in the design doc before any website code.
    5. 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.
    6. 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.

  5. sefk commented on Nov 16, 2026

    @sefk
    ContributorAuthor

    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_caller accepts user:<32 hex> beside the website's shared secret, as a new "account" caller kind.
    • Deploy-time maintenance now keeps user: pin principals instead of rewriting them as raw secrets.
    • Tests cover callers, allowances, pins and maintenance.

    dfo-ai feat/keyed-caller (52808cb)

    • The data, presentation and analysis clients forward user: callers to dfo-apis, as they forward ip: callers.
    • Full suite: 15,689 passed.

    website feat/api-keys (9 commits, 14efb73..c13d579)

    • 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.
    • Docs quickstart and the infra job.
  6. sefk commented on Nov 16, 2026

    @sefk
    ContributorAuthor

    From Claude Code, on behalf of @sefk.

    Pull requests for this phase, in the order they must merge and deploy:

    Order Repo Pull request Why this order
    1 dfo-apis apis#320: accept an account caller from the website dfo-apis answers 400 to a user: caller until this is live
    2 dfo-ai ai#201: forward account callers to dfo-apis Without this, dfo-ai drops user: callers, so keyed MCP use counts against dfo-ai itself
    3 website website#143: API keys with per-account rate limits (design and implementation) Starts sending user: callers, so it ships last. Merging #149 first keeps the just stack commits out of its diff
  7. sefk commented on Nov 16, 2026

    @sefk
    ContributorAuthor

    From Claude Code, on behalf of @sefk.

    Updated merge order, now with the docs, spec-kit and infra pull requests:

    Order Repo Pull request Why this order
    1 docs docs#26: "Use an API key" page The dfo-apis and dfo-ai guide pages link to it, and the docs build's link check fails until it exists
    2 dfo-apis apis#320: accept user: callers; the quickstart says a key is optional dfo-apis answers 400 to a user: caller until this is live
    3 dfo-ai ai#201: forward user: callers; the MCP connect page covers keys Otherwise keyed MCP use counts against dfo-ai itself
    4 website website#143: API keys, design and implementation Starts sending user: callers. Merging #149 first keeps the just stack commits out of its diff
    5 infra infra#150: ADMIN_EMAILS from Secret Manager Then add the real admin list with gcloud secrets versions add and roll a revision
    any spec-kit spec-kit#57: the invalid_api_key code 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P1Major: a feature is broken or data is wrong, with a workaround. Fix this cycle.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions