Stable per-user API tokens

[dorian-pltr]

I've been running Spliit Cloud for a while and wanted to point an agent at my own data. Nothing exotic, mostly adding expenses from a script and reading balances back out. Turns out there's no way to do it: sessions are cookie-bound, and the OAuth path is wired specifically for MCP.

ROADMAP.md already flags this in Phase 4, "Stable per-user API tokens remain planned". CONTRIBUTING.md asks for an issue before larger changes, so this is a design proposal rather than a surprise PR. I'd rather agree on the shape before writing any code.

Where things stand

Three credentials exist today. None of them work for a script.

Session cookies reach everything behind protectedProcedure, but they're browser-bound. There's no issue/scope/revoke story for a headless client.

OAuth through the oauth-provider plugin gets you four procedures on the assistant router. It's gated behind ENABLE_MCP, the audience is pinned to the MCP endpoint, and it wants a public tunnel plus an interactive consent flow. That's the right design for ChatGPT and Claude connectors. It's the wrong one for a cron job.

Group bearer tokens are read-only and scoped to a group rather than an account.

So the OpenAPI document advertises 163 operations and nothing outside a browser can authenticate against a single one.

Design

Resolution. AuthContext.auth in trpc/init.ts is already a union discriminated on credentialKind, and the context factory already chains two resolvers. I'd follow that seam rather than widen it: add an ApiKeyResolvedAuth variant mirroring OAuthResolvedAuth, add a resolver reading x-api-key, chain it.

Authorization. protectedProcedure keeps rejecting non-session credentials, the same way it already rejects OAuth ones. That's what makes the first step safe: no existing procedure changes behaviour. Access comes instead from a new apiProcedure(scope), taking a session or a key carrying that scope, reusing the spliit:* namespace the OAuth provider already established (spliit:groups:read, spliit:expenses:write, and so on).

Storage. The @better-auth/api-key plugin, which matches the better-auth version already pinned here. It covers hashing, prefixes, a short fragment for rendering keys safely in a UI, expiry, per-key rate limiting and metadata. Its table needs the same kind of modelName override the other better-auth models already use, plus a migration.

I'd skip enableSessionForAPIKeys, since it promotes a key to a full session and throws away the scoping above.

Surface. Create/list/revoke procedures under account, plaintext returned once at creation. A settings section next to the existing account ones. A securitySchemes.apiKey entry so /docs documents the header.

Splitting it up

1. Plugin, schema mapping, migration, the new auth variant and apiProcedure. Nothing exposed yet.
2. Management procedures and settings UI.
3. apiProcedure applied to groups and expenses.
4. OpenAPI security scheme and docs.

Stopping after any of them leaves the tree coherent.

Where I'm unsure

Scope shape. Domain and verb is the obvious axis, but per-group scoping (a key that only ever sees one ledger) might be worth having from the start instead of retrofitted. I genuinely don't know which way you'd want this.

Rate limiting. The plugin ships a per-key limiter and the repo already has FixedWindowLimiter. Layering both is wasteful, picking one feels arbitrary from outside. Preference?

No env flag. I'd rather not gate this one. ENABLE_MCP earns its flag because it has real config dependencies and the API won't boot without them. API keys have nothing to provision, so a flag would only add an ops decision on top of the merge, Spliit Cloud included. Push back if you see it differently.

Anonymous accounts presumably can't issue keys, consistent with the checks elsewhere. Assuming that's right.

Once those are answered and the direction looks right to you, I'm happy to take the implementation from there and open the PRs.

[pullfrog]

Maintainer triage: Stable per-user API tokens

What is being requested

A way for headless clients (scripts, cron jobs, personal agents) to authenticate against the Spliit Cloud API with the user's own credentials. Today nothing outside a browser can call the protected surface: cookie sessions are browser-bound, the OAuth path (assistant router) is gated behind ENABLE_MCP and pinned to the MCP endpoint (needs a public tunnel + interactive consent), and group view keys are read-only and group-scoped. The underlying need is simple: "I want to write scripts that add expenses and read balances as me, without keeping browser cookies around."

The proposal is not just a credential type but an authorization story: keys carry scopes (spliit:* from the OAuth namespace), are stored hashed via @better-auth/api-key, exposed once in plaintext at creation, manageable from account settings, and surfaced in /docs as an apiKey security scheme.

On the author's technical claims

I verified the key claims against the code and they are accurate:

• AuthContext.auth is already a union (ResolvedAuth | OAuthResolvedAuth | null) in apps/api/src/trpc/init.ts, and the context factory chains the session and OAuth resolvers — the proposed seam is real.
• protectedProcedure explicitly rejects credentialKind === 'oauth', so a new apiProcedure that accepts key auth is purely additive — no existing procedure would change behavior.
• The OAuth provider (in apps/api/src/lib/auth/index.ts) uses validAudiences: [MCP_PUBLIC_URL/mcp] and the scopes spliit:groups:read / spliit:expenses:write; the assistant router has exactly the four procedures described.
• The OpenAPI document's only securitySchemes entry is the session cookie; per-operation security is layered in scripts/generate-openapi.ts.
• @better-auth/api-key@1.6.25 exists and peer-depends on better-auth ^1.6.25, matching the pinned ~1.6.25 — the plugin-version claim checks out. It is not bundled inside better-auth (the api-key plugin was extracted), so it'd be a new dependency rather than a config-only enable.

Ambiguities / missing context

• Scope shape (explicitly deferred by the author). Domain+verb vs. starting with per-group scoping changes the data model (scope strings on a key vs. a group-bound key), the permission checks, and the management UI. This is the single biggest scope/design fork and should be settled before implementation.
• Coverage of non-tRPC routes. The published OpenAPI includes non-tRPC read routes (group export/report endpoints) that currently authenticate via cookie or public view key. It's not stated whether API keys should cover those, or only tRPC procedures.
• Anonymous accounts. The author assumes they can't issue keys. This is consistent with the existing ANONYMOUS_SETUP_REQUIRED gate, but it's still a policy choice worth stating (anonymous accounts that completed onboarding are still isAnonymous).
• Env flag. The author proposes no gate. The repo has a convention of gating features (ENABLE_MCP, PUBLIC_ENABLE_BULK_CATEGORIZE), so self-hosters may expect an opt-out even if there is nothing to provision.

Technical feasibility

Feasible, with a few conceptual decisions. The auth seam, the additive-procedure pattern, and a version-matched plugin all exist. The main costs are a new DB table + migration (the same modelName-override pattern the existing better-auth models use), a new auth resolver (a third link in the chain, currently two), the apiProcedure factory, and wiring key-based identity into rate limiting. Nothing about this is architecturally incompatible; the genuinely tricky parts are decisions, not mechanics.

Blast radius

Moderate and cross-cutting, but mostly additive:

• Auth / permissions — new credential kind, new procedure factory, scope enforcement.
• Database — new key model + migration; no changes to existing tables.
• API surface — new account management procedures; /docs security scheme.
• Web — account settings section; strings via bun i18n.
• Rate limiting / abuse — existing account-keyed limiters (FixedWindowLimiter); per-key limits are layered on top of, not replacing, them.
• Group view keys and OAuth — untouched, though keys could eventually subsume some view-key use cases; the shared spliit:* scope namespace means two auth flows produce the same scope strings, which is fine unless it muddies the OAuth consent screen.

Consequences and edge cases

• Security: plaintext-once keys, hashed at rest (plugin behavior), x-api-key in headers (log hygiene), immediate revocation, expiry/rotation. Keys scoped to expenses:write can mutate money data, so per-key limits and the existing account mutation limiter both matter.
• Backward compatibility: purely additive if protectedProcedure stays unchanged — no existing client breaks. The author's four-stage split is genuinely stop-safe.
• Rate limiting: the author flags the layering question. Worth noting the repo already has account-scoped limiters in the request path (authenticatedMutationLimiter, AI/import/presign quotas); per-key limits keyed by account would be the aggregate story, per-key the granular one. Whichever is chosen, a key must not silently bypass the account-level mutation limiter it was issued to.
• Migration discipline: new migration prefix must sort after all existing folders (bun --filter @spliit/db prisma-create-migration).
• E2E encryption tension: ROADMAP Phase 4 also plans end-to-end encrypted groups — if ledgers eventually move to client-side encryption, a server-held key that reads/writes plaintext expenses would be incompatible with that goal. The API-key feature should be designed to coexist or at least not entrench server-readable plaintext further.

Scope assessment

Moderate / cross-cutting. It touches auth, DB, API procedures, docs, and the settings UI, but every piece is localized and additive, and the author's staged breakdown is a sensible framing. It is not a small, localized change (persists across five areas), and it is not fundamental (no re-architecture of the existing session/OAuth model).

Open questions (before implementation)

1. Scope model: domain+verb only, or per-group-scoped keys from day one?
2. Rate limiting: plugin per-key limiter, repo FixedWindowLimiter, or both keyed on what identity — and how do keys interact with the existing per-account mutation limiter?
3. Coverage: tRPC procedures only, or also the non-tRPC export/report routes in the OpenAPI?
4. Env flag: confirm the no-flag stance vs. self-hoster expectation of an opt-out.
5. E2E encryption: how does a server-held plaintext API key coexist with the planned end-to-end encrypted groups?
6. Anonymous accounts: confirm the policy that they cannot issue keys.

Maintainer summary

1. The real ask: stable, per-user, revocable, scope-limited API keys so the author's own scripts (and general headless/agent clients) can read balances and add expenses — generalizing the "plumbed for MCP only" OAuth surface into a general-purpose credential.
2. Feasible: yes — the additive auth seam, the rejection of non-session credentials, and a version-matched @better-auth/api-key@1.6.25 all support it with low risk to existing behavior.
3. Blast radius: moderate/cross-cutting — auth layer, new DB table + migration, new account procedures, /docs scheme, settings UI, rate-limit interplay.
4. Most important unresolved question: the scope model (domain+verb vs. per-group), followed closely by the E2E-encryption interaction — both materially change the shape of the data model and should be settled before the first PR.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using openai-compatible/deepseek-v4-flash-free ｜ 𝕏}

[antonio-ivanovski]

@dorian-pltr I am undecided on this topic too, i am unsure whether API keys are being the solution or oauth - or maybe both. Would maybe start with exposing oauth to be not feature-fated by the MCP impl and also allow for oauth sessions to be revokable in the settings. Also proper scopes must be defined so that agents don't have permission to delete expenses or groups or other more destructive actions.

I would be more then happy if you open a PR with this definition, keeping what we already have. API keys can be added in the future if AI agents have bad time with oauth.

[dorian-pltr]

Sounds good, happy to go with OAuth rather than API keys.

I noticed mcp.spliit.cloud is 404 on everything right now, including the oauth well-known, api.spliit.cloud is fine. It means that discovery is dead for new clients, which sort of makes your point about ungating.

One thing I missed in the issue: groupReadProcedure rejects OAuth too, not just protectedProcedure, and that's where all the group reads live. Both need handling or an agent can create an expense but not read it back.

Scopes: groups/expenses read and write as the default set, delete as its own scope that's never granted unless asked for.

I went ahead and built it: #101.

Ungating turned out to be three places rather than one, the provider plugin, the jwt plugin it depends on, and the four .well-known routes in app.ts. Revocation needed more than the plugin's own delete-consent, which only drops the consent row and leaves the client refreshing until its refresh token expires, so it now revokes the refresh tokens in the same transaction.

The audience is the one thing I'd like you to call. Tokens your assistant clients already hold carry ${MCP_PUBLIC_URL}/mcp, so I made the API accept both that and its own audience while the variable is set, rather than signing everyone out on deploy. Easy to change if you'd prefer forcing reauthorization.

Destructive scopes are isolated in their own commit, so you can drop that one and still take the rest.

Also opened #100 separately: .env.example doesn't boot from a clean clone. The three MCP_* values are the cloudflared command lines from the docs pasted in as values, so Zod rejects them and turbo takes the whole bun dev down. Unrelated to this, just hit it while setting up.

Two things worth their own issue, happy to file them if useful. import-recurrence.test.ts fails on main. And the API test suite is order-dependent under load, I measured 21, 29 and 21 failures across three runs on a clean main while the same files pass in isolation, so CI may be flaky for reasons unrelated to any given PR.