API contract for programmatic clients

The HTTP surface (src/BookTranslation.Api) is the substrate the web app, the MCP server, and the desktop apps all consume. This document is the stable contract an agent/MCP client codes against: the error envelope, the idempotency guarantee, the list convention, and the discovery endpoint. Shipped by PBI #1428 (Feature #1410, Public API GA). It complements docs/spec.md §7.

The driving constraint: an agent can't pattern-match a human sentence. Every response is shaped so a client can branch on typed, predictable fields — never on prose that may be reworded.

1. Errors — RFC 9457 ProblemDetails

Every non-2xx response is a single application/problem+json envelope:

{
  "type":   "https://kenly/errors/project_wrong_state",
  "title":  "Invalid state transition",
  "status": 409,
  "detail": "Cannot 'normalize' from state 'Calibrating'. Expected: Created.",
  "code":   "project_wrong_state"
}

• code is the contract. It is a stable, machine-readable string clients switch on. title/detail are human-facing and may be reworded; code and type (which is https://kenly/errors/{code}) will not change for a given condition.
• The shape is produced in exactly one place — the ApiProblem factory in src/BookTranslation.Api/ApiContract.cs, plus a registered IExceptionHandler that maps an uncaught InvalidProjectStateException through the same factory — so it cannot drift per endpoint.
• Domain extras ride along as typed extension members, not a different top-level shape: a 402 carries the affordability quote.

Stable codes

code	Status	Meaning
validation	400	A field was missing, malformed, too large, or otherwise invalid.
invalid_credentials	401	/auth/login credentials did not match.
insufficient_credit	402	The wallet can't cover the next batch. Carries quote (a BatchQuote).
project_not_found	404	No project with that id exists for the caller (owner-scoped; never leaks existence).
account_not_found / job_not_found / notification_not_found / avatar_not_found / source_not_found / export_not_found / image_not_found	404	The named resource was not found.
topup_not_found	404	No top-up/redeem with that reference exists for the caller (GET /v1/wallet/top-up/{reference}; owner-scoped).
email_taken	409	Registration: the email already has an account.
project_wrong_state	409	A pipeline transition was invoked from a state its guard forbids.
no_failed_pages	409	POST /projects/{id}/retry when the project has no failed pages to retry.
queue_changed	409	The queue changed under a reorder (an item started/finished).
idempotency_in_flight	409	An identical request for the same operation is already being processed (server-side dedup, §2); retry shortly.
rate_limited	429	The per-principal request rate limit was exceeded. Carries Retry-After + RateLimit-* headers (§8).

2. Idempotency — internal, no client action (PBI #2120)

Retry-safety is a pure backend concern. There is no client Idempotency-Key header — a client never sends, reads, or sees an idempotency key. For each billable / state-changing POST the server derives a stable dedup key from the request content and the project's current state, so a double-submit can't double-charge or double-enqueue. This protects even clients that would never have thought to send a key.

Internal-only mechanics (not part of the public contract; documented here so the behaviour is traceable):

• Server-derived keys. Project transitions (normalize, process, process-next-batch, export, retry, cancel) key on {scope}:{owner}:{projectId}:{state}, where {state} is the status + batch cursor (ApprovalCount), or the failed-page set for retry — so a duplicate of the same operation is deduped while the legitimately-next one composes a fresh key. The wallet purchase (§6) has no state cursor, so it keys on the request content (owner + amount + method + card) within a short time window: a double-submit collapses while a deliberate repeat after the window proceeds.
• Precision trade-off (flagged). A server-derived content+window key is slightly less precise than a client-chosen one: two intentional identical top-ups in the same short window would collapse into one. Acceptable for this app; the simplification is worth it.
• Pre-reservation guards. Affordability (402) is checked before the key is reserved, so a rejected attempt is never cached.
• Fail-open. Backed by Redis (the Aspire cache resource) via IIdempotencyStore; if Redis is unreachable the store returns Bypassed and the endpoint proceeds (retry protection is lost for that request, availability is not). With no Redis configured (a bare dotnet run or the tests) an in-memory store with identical semantics stands in. See CLAUDE.md → Redis (cache) + idempotency.

3. List convention

Collection endpoints return a bare JSON array. The one exception is the searchable, sortable, paginated project library — GET /projects — which returns a PagedResult envelope:

{ "items": [ … ], "total": 128, "page": 1, "pageSize": 25 }

4. Versioning + OpenAPI (PBI #1427)

The whole surface is served under a stable /v1 base path (e.g. POST /v1/projects). A narrow server-side back-compat rewrite still accepts the old unversioned paths, so /projects is an alias for /v1/projects — older clients keep working while /v1 is the versioned contract.

A generated OpenAPI 3 document is served at GET /openapi/v1.json (.NET 10 first-party Microsoft.AspNetCore.OpenApi). Every operation has a stable operationId, a resource tag, and typed request/response + ProblemDetails (402/404/409) responses; the document declares the Bearer (JWT) and ApiKey (X-Api-Key, PBI #1426) security schemes so a code generator / MCP server can authenticate.

4a. One cross-surface status/event contract (PBI #2006)

Every surface — the SPA, the MCP server (#1433), a future mobile app, outbound webhooks (#2003) — reasons about the same book status + lifecycle events, so the contract for them is published once, typed, in the OpenAPI doc and generated against (never hand-duplicated):

• The status DTO (ProjectStatusView, GET /v1/projects/{id}/status, #2000/#2004) and the lifecycle event (ProjectLifecycleEvent, GET /v1/projects/{id}/events, #2002) are named schemas in the doc.
• Their closed taxonomies are declared as enum types so a generated client gets exhaustive, non-drifting string-literal types instead of a bare string: state · phase (intake｜working｜waiting｜done｜error｜cancelled) · waitingOn (gpu_capacity｜gpu_warmup｜queue｜credit) · blockedOn (credit｜retry) · nextAction (add_credit｜retry｜download), plus the transition event (create｜normalize｜processBatch｜retry｜ autoAdvance｜cancel｜finalizeCancel). waitingOn=credit is reserved — published for forward-compat but never emitted (an out-of-credit book is blocked, not waiting; see book-status-state-machine.md §4.2). Each set is also published as a reusable, named enum schema (ProjectPhase, ProjectWaitingOn, …).
• The enums are single-sourced from the server's own constants (ProjectStatusTaxonomy, ProjectLifecycleEventNames, the ProjectStatus enum) via an OpenAPI document transformer, so the published contract and the emitted payloads cannot diverge. Two conformance tests enforce it and fail CI on any break: StatusEventContractConformanceTests (every value the server can emit is inside the published set — always-on, no container) and OpenApiContractTests (the doc declares exactly those enums).
• The SPA generates its types from the doc: a focused slice src/BookTranslation.Web/openapi/status-contract.json is committed and npm run codegen turns it into src/api/generated/status-contract.ts (re-exported from src/api/types.ts). StatusContractSpecTests guards the committed slice against the live doc.

4b. Versioning rule — additive-only within /v1

/v1 is a stable, additive-only contract. Within /v1 we only ever make backward-compatible changes, so a generated agent/mobile client never breaks silently:

• Allowed (additive): new endpoints; new optional response fields; a new value appended to a closed enum only when every documented consumer already treats the enum as open / has a default branch (e.g. activating the reserved waitingOn=credit); new optional request parameters with safe defaults.
• Breaking (requires a new version, e.g. /v2): removing/renaming a field or endpoint; changing a field's type or making an optional field required; removing an enum value; changing the meaning of an existing value. A breaking change is a new versioned surface, never an in-place edit of /v1.

Because the enum sets are single-sourced and conformance-tested, an accidental breaking change (e.g. deleting an enum value the DTO still emits, or renaming one) fails CI rather than shipping.

4c. Real-time push — SignalR + signed webhooks (PBI #2003)

Clients don't have to poll: the server pushes a book's status the instant it changes, over two transports driven off the same #2002 event log, both carrying the §4a ProjectStatusChange envelope (the durable event with its eventId replay cursor + the current status DTO — the same shape GET …/status returns).

• SignalR hub (the SPA) — GET /v1/hubs/status (WebSocket). Authenticated with the same JWT as the REST API (it rides via the access_token query on the handshake). Each connection joins only its own owner group, so a client can never receive another account's events (cross-tenant subscription is impossible — the group is keyed by the authenticated uid, never client input). Server → client method statusChanged delivers the envelope; the client method CatchUp(projectId, afterEventId) replays missed events from the last id it saw, so a reconnect never drops a terminal state. A Redis backplane (the Aspire cache) makes it work across multiple API instances.
• Signed webhooks (headless agents / MCP) — register per-owner endpoints under /v1/webhooks (POST to register — the signing secret is returned once; GET to list without secrets; DELETE to remove). Each delivery is a JSON POST of the envelope, HMAC-SHA256 signed with the subscription secret: header X-Kenly-Signature: t=<unixSeconds>,v1=<hex> over "{t}.{body}" (Stripe-style — the t makes it replay-checkable), plus X-Kenly-Event-Id for idempotent receivers. Delivery retries with exponential backoff; an exhausted delivery is recoverable via the GET …/events replay feed.

5. Discovery — GET /v1/meta

Anonymous (no token required) so a client can self-configure before it authenticates:

{
  "apiVersion": "1.0",
  "batchLadder": [1, 5, 25, 100],
  "finalBatch": "rest",
  "exportFormats": ["All","Markdown","PlainText","Html","Epub","Docx","Pdf","Archive"],
  "problemTypeBase": "https://kenly/errors/"
}

The OpenAPI document is the discovery mechanism for the closed vocabularies (PBI #2112). There is deliberately no separate public /v1/discovery endpoint — a runtime endpoint would duplicate contract facts into a second source of truth that can drift. Instead the published doc (GET /openapi/v1.json) self-describes the app-wide facts a typed SDK/MCP client needs, as enums/constants it self-configures from: the API version (info.version), the export formats (ExportFormat enum), and the destination languages — targetLanguageCode is constrained to the supported ISO-639 set (published once as the reusable TargetLanguageCode component schema) everywhere a client chooses a destination language (the create-project body and the anonymous-estimate query). The source language is auto-detected and is never enumerated. /v1/meta stays Internal because it also carries deployment/feature-flag internals a public client must not see (OAuth client ids + enablement, payment-rail flags, the batch ladder, the problem-type base). Mechanically this mirrors the status/event contract (StatusContractDocumentTransformer) — see LanguageContractDocumentTransformer + OpenApiContractTests.

Model-backend readiness — GET /v1/model-status (PBI #1833)

Anonymous, poll-friendly. Reports whether the real model backend is up and GPU-ready right now, so the SPA can show a "GPU infrastructure is starting, please stand by…" banner and gate the process action instead of letting it fail (the graceful counterpart to the fail-closed backend, #1840):

{
  "backend": "RunPod",
  "isReal": true,
  "ready": false,
  "state": "starting",
  "detail": "GPU infrastructure is starting (cuda:false (device=cpu))"
}

• state is ready | starting (a real backend that is cold/unreachable) | unconfigured (no backend configured); ready is the convenience boolean (state == "ready"). isReal surfaces ModelBackendInfo.IsReal (true only for RunPod).
• The readiness check runs the worker's health op through the same RunPodClient transport that serves real OCR/translation, so it is pod/serverless-agnostic — identical behaviour on the dev persistent pod and a production serverless endpoint (only BaseUrl/EndpointId differ; see docs/runbooks/runpod-model-processing.md §3).
• The result is cached for a short TTL server-side (and coalesced), so many polling tabs trigger at most one backend health call per window — important on serverless, where a health op can wake a worker.

6. Agent wallet surface — /v1/wallet (PBI #1429)

The machine-callable credit surface the MCP purchase_tokens tool (#1433) binds to: read the balance and add credit without a human opening the web app. A thin, versioned layer over the one credit-grant routine (docs/payments.md §2) — it adds no second ledger; every credit is a confirmed CreditTransaction. All routes require auth and are owner-scoped.

Method & route	Body	Returns
GET /v1/wallet	—	{ balanceUsd, currency, unlimited, lowBalance }
POST /v1/wallet/top-up	{ amountUsd, method?, coin?, savedCardId? }	{ reference, status, method, amountUsd, creditedUsd, balanceUsd, checkoutUrl?, message, cryptoCoin?, cryptoAddress?, cryptoAmount? }
GET /v1/wallet/top-up/{reference}	—	the same top-up view (poll)
POST /v1/wallet/redeem	{ code }	a confirmed top-up view

POST /v1/wallet/top-up is the ONE canonical way to add credit (#2114 — it consolidated the former /wallet/top-up + /wallet/checkout + /wallet/checkout-saved-card, which no longer exist). One call, one unified response: either status: confirmed (credit landed now) or status: pending with a checkoutUrl to complete (poll GET /v1/wallet/top-up/{reference} until confirmed). Routing by method:

method	+	Behaviour
card	savedCardId	Charges that saved card in-app — credit lands immediately (confirmed).
card	—	Returns a hosted Stripe Checkout checkoutUrl (pending); completable headlessly.
crypto	coin?	Returns a hosted CoinPayments checkoutUrl (pending) for the chosen coin.
manual	—	Credits immediately (confirmed) — development-only (see below).

• Card model (PCI). Raw card numbers must never touch this API, so saving a new card happens on Stripe's hosted page — method=card with no savedCardId returns a hosted checkoutUrl the user opens once. After a card is saved, charging it is pure API: pass its savedCardId (from GET /v1/payment-methods) and the charge happens in-app, no browser. So the model is: new card → hosted URL (once); saved card → API charge; crypto → hosted URL.
• manual (instant credit) is development-only. It credits with no payment taken, so it is off in production/UAT (BookTranslation:Billing:ManualCreditEnabled, default = Development-only). A manual request on a production deployment is rejected validation (400) — a public caller can never mint free credit. Pay by card or crypto instead.
• Retry-safety is automatic and backend-owned (§2). The server derives its own dedup key from the purchase (owner + amount + method + card + a short time window) and forwards it to Stripe, so a double-submit within the window can't take money twice — the caller sends no header. Hosted checkout / crypto flows are naturally single-use.
• status is lowercase (confirmed / pending / failed / cancelled / expired); method is manual / card / crypto. method defaults to manual when omitted.
• lowBalance is true once a charged wallet falls to/below the configured threshold (BookTranslation:Billing:LowBalanceThresholdUsd, default $1) — the cue to prompt a top-up before the next batch is blocked with insufficient_credit (402).
• Redeem codes (POST /v1/wallet/redeem, BookTranslation:Billing:RedeemCodes) are a separate operator-issued mechanism (not consolidated): redeeming a configured code credits immediately so a 402'd batch can resume. Single-use per owner; an unknown or already-redeemed code is validation (400).
• Errors: out-of-bounds amount / unknown method / manual in production / bad code → validation (400); unknown reference → topup_not_found (404).

7. Authentication — JWT + API keys (PBI #1426)

Every non-auth endpoint accepts either credential, both resolving to the same owner identity (the same owner-scoped 404-on-cross-tenant behavior applies to both):

• Interactive JWT — a 12-hour bearer token from POST /v1/auth/login / /v1/auth/register, sent as Authorization: Bearer <jwt>. For the browser SPA.
• Scoped API key — a long-lived, revocable secret for headless agent/MCP clients, sent as Authorization: Bearer kenly_sk_live_… or X-Api-Key: kenly_sk_live_…. A "smart" auth scheme picks the handler per request by the credential shape.

Key management (owner-scoped, under /v1/api-keys):

Method & route	Body	Returns
POST /v1/api-keys	{ name, scopes?, expiresInDays? }	{ id, name, prefix, scopes, createdAtUtc, expiresAtUtc, secret } — secret is shown exactly once
GET /v1/api-keys	—	[{ id, name, prefix, scopes, createdAtUtc, lastUsedAtUtc, expiresAtUtc, revokedAtUtc }] (never the secret)
DELETE /v1/api-keys/{id}	—	204; revocation is immediate

• Capability boundary — key management + identity/security are interactive-only (PBI #2117). An API key can do everything the product does for its owner (create/drive/observe projects, upload, read the wallet + buy credit, manage webhooks, read the account, edit low-risk preferences), but it can never mint another credential or change identity/security settings — the OpenAI/Stripe/Cloudflare model. Concretely, an API-key principal is rejected with 403 interactive_auth_required on: POST /v1/api-keys (mint a key), DELETE /v1/api-keys/{id} (revoke a key), DELETE /v1/me (delete the account), POST /v1/me/change-password (rotate the password, §7b), POST /v1/me/set-password (add a first password to an OAuth-only account, §7b-i), and POST /v1/me/change-email (change the login email, §7c). An interactive JWT (a human in the dashboard) is accepted on all of them. GET /v1/api-keys (observe) stays open to both. Create your first key in the web dashboard (JWT), then use it for everything else.

7b. Change password (PBI #2124)

A signed-in user rotates their own password without triggering the forgotten-password email:

Method & route	Body	Returns
POST /v1/me/change-password	{ currentPassword, newPassword }	200 { changed: true, token }

• Interactive-only (§7). An API-key principal is rejected with 403 interactive_auth_required before any password check; an interactive JWT is accepted.
• Current-password gated. The currentPassword is verified against the stored hash — a mismatch is 403 password_incorrect and nothing is persisted (mirrors the DELETE /v1/me confirmation).
• New-password rules. newPassword must meet the minimum-strength rule and differ from the current one; either failure is 400 validation with the requirement message.
• OAuth-only accounts. An account that signs in only through Google / Apple has no password to change → 409 password_not_set (a clear, non-leaky message — never a 500). Setting a first password on such an account is out of scope (a separate flow).
• On success the new password is re-hashed + persisted, a best-effort security audit event is recorded (actor uid, UTC, request IP / UA — never blocks the change), and a fail-soft "password changed" alert email is sent to the account address (a send failure never fails the change).
• Rate-limited per principal (anti-brute-force on the current-password confirmation): over the per-uid ceiling returns 429 with the uniform RFC-9457 body + Retry-After / RateLimit-* headers (§8).
• Signs you out everywhere else (PBI #2126, §7d). The change rotates the account's security stamp, so every other session's token is revoked (401 on its next call). The response returns a fresh token for the acting (calling) session — swap your stored JWT for it so the device that changed the password stays signed in.

7b-i. Set a first password — OAuth-only accounts (PBI #2154)

A user who signed up with Sign in with Google / Apple has no password (PasswordHash is empty), so they can use neither §7b (change password) nor §7c (change email) — both re-enter a current password there is none of. This adds a password in-session as an optional backup sign-in method (the gold standard: one account, multiple methods). It is structurally §7b minus the current-password verify plus a guard that the account does not already have a password.

Method & route	Body	Returns
POST /v1/me/set-password	{ newPassword }	200 { changed: true, token }

• Interactive-only (§7). An API-key principal is rejected with 403 interactive_auth_required before any work; an interactive JWT is accepted.
• No current password. There is none to confirm — the interactive session is the authorization.
• New-password rule. newPassword must meet the minimum-strength rule; a too-weak password is 400 validation with the requirement message.
• Already has a password → non-leaky 409 password_already_set. An account that already has a password must use §7b (change password, which verifies the current one) — this endpoint only ever adds a first password and never silently overwrites an existing credential (so it can never remove the last sign-in method).
• On success the password is hashed + persisted, a best-effort security audit event is recorded (account.password_set — actor uid, UTC, request IP / UA), and a fail-soft "password added" alert email is sent to the account address (a send failure never fails the change). After this the account has both the external provider and password sign-in.
• Signs you out everywhere else (PBI #2126, §7d). Adding the password rotates the account's security stamp, so every other session's token is revoked; the response returns a fresh token for the acting session — swap your stored JWT for it so the device that added the password stays signed in. A subsequent GET /v1/me then reports hasPassword = true, so the SPA flips from the "Create a password" form to the normal change-password / change-email forms.
• Rate-limited per principal (§8): over the per-uid ceiling returns 429 with the uniform RFC-9457 body + Retry-After / RateLimit-* headers.

7c. Change email — verify-before-flip (PBI #2125)

A signed-in user changes their login email safely. The design decision is verify-before-flip: the account email is not touched until the new address proves ownership — so a typo or a hijacked session can never strand a real user out of their account, and the change is always visible to the current owner.

Method & route	Auth	Body	Returns
POST /v1/me/change-email	JWT only	{ newEmail, password }	202 { pending: true } — login email unchanged
POST /v1/auth/confirm-email-change	anonymous (token)	{ token }	200 { changed: true } — email flips now
POST /v1/auth/cancel-email-change	anonymous (token)	{ token }	200 { cancelled } — old-address kill switch
POST /v1/me/change-email/cancel	JWT/key	—	200 { cancelled } — in-app cancel

• Initiate (POST /v1/me/change-email). Interactive-only (§7 — an API key is 403 interactive_auth_required) and current-password gated (mismatch → 403 password_incorrect, mirroring §7b / DELETE /v1/me). The new address is validated + normalized (invalid → 400 validation; equal to the current address → 400); an address already registered to another account → 409 email_taken. On success the login email is not changed — a pending change is recorded, a single-use verification link is emailed to the new address, and a "this wasn't me" cancel alert to the old address (the out-of-band takeover-detection channel, which names only the masked new address). An OAuth-only account (no password) is a non-leaky 409 password_not_set.
• Confirm (POST /v1/auth/confirm-email-change). Anonymous — the single-use token from the new-address link is the credential (mirrors verify-email / reset-password). On a valid token the login email flips to the pending address, EmailVerified is set true (ownership just proven), the token + its paired cancel token are consumed, and an "email changed" confirmation is sent to the old address. email_taken is re-checked at confirm time — if the address was registered elsewhere in the interim, 409 email_taken and the change is not applied. An unknown / used / expired token is a non-leaky 400 invalid_email_change_token.
• Cancel (either route). A pending change can be cancelled by the signed-in user (POST /v1/me/change-email/cancel, owner-scoped, idempotent) or by the real owner via the old-address alert's cancel link (POST /v1/auth/cancel-email-change, anonymous token). Either burns the pending change so the outstanding verify link can no longer complete. The two links carry distinct secrets — the old address gets only the cancel secret, so the owner can abort a change they didn't start without ever being able to complete it.
• On both events a best-effort security audit event is recorded (account.email_change_requested / account.email_changed — actor uid, UTC, request IP / UA, the masked new address; never blocks the action). All emails are fail-soft (a send failure never fails the operation).
• Rate-limited (§8): the initiate is capped per uid (anti-brute-force on the password + anti-mail-bomb on the new/old addresses); confirm + cancel are capped per IP. Over the ceiling → 429 with the uniform RFC-9457 body + Retry-After / RateLimit-* headers.
• Signs you out everywhere (PBI #2126, §7d). Confirming the flip rotates the account's security stamp, so every existing session is revoked — the confirm is an anonymous link flow with no live JWT session to preserve, so the user simply signs in fresh with the new address.

7d. Session invalidation on credential change (PBI #2126)

Every JWT is stamped with the account's current security stamp (a stamp claim). Each authenticated request validates that claim against the stored value, and any credential change rotates the stamp — so one write invalidates every outstanding token at once. This is the gold-standard "changing your password signs you out everywhere else" behaviour, and it means a stolen or leaked token is cut off the moment the owner rotates a credential.

• What rotates the stamp: an authenticated password change (§7b), a forgotten-password reset (POST /v1/auth/reset-password), and an email-change confirm (§7c). A token minted before the change returns 401 on its next call.

• Acting-session continuity. The one flow with a live JWT session — change-password — returns a fresh token carrying the new stamp so the calling device stays signed in. The two link-completion flows (reset, email-change confirm) are anonymous and end at the sign-in screen, so the user authenticates fresh; there is no live session to re-issue.

• API keys are unaffected. A kenly_sk_… principal carries no stamp and is never gated by this check — keys are a separate, independently revocable credential (revoke them under /v1/api-keys).

• Cost + the trade-off. Validation is a short in-memory cache of each user's current stamp over a single indexed primary-key read: the common case (a matching token) is one memory hit with no database round-trip. A mismatch is always re-confirmed against the store before it 401s, so a just-re-issued token is never wrongly rejected by a stale cache. The cache can lag the database by up to ~30 s, so on a multi-instance deployment a revocation reaches instances that cached the prior value within that window (the instance that made the change evicts its own entry immediately) — an availability-over-immediacy choice that is still far tighter than ASP.NET Identity's 30-minute default. Validation is fail-safe: a lookup error admits the request rather than locking everyone out.

• Out of scope: refresh-token rotation, a device/session-management UI, and sliding-expiration changes.

• Storage: only a SHA-256 hash of the secret is persisted; the raw kenly_sk_live_… value is never stored or logged. The non-secret prefix is kept for display + leak scanning.

• Scopes describe a key's intended capability and are recorded on the key and echoed back when you list it. The recognized set is projects:write (the default — read/write) and projects:read (read-only); a create request for any other token (including the retired approve scope) is rejected with validation (400). A revoked or expired key is 401 (distinct from a 401 for an unknown credential). A JWT (a human) authenticates with full capability.

  • Enforcement today. The only scope-gated route was the per-page human-approval endpoint, removed in #1455 (translation is fully automatic, review is read-only). With it gone, the approve scope had nothing left to guard and was removed in #2073; projects:read/projects:write are carried as a forward-compatible seam but are not yet enforced per route — a valid key authenticates for every owner-scoped operation regardless of its scope. Finer read-vs-write route enforcement is additive future work (Feature #1410); when it lands it will only ever tighten a read-only key, never loosen the default write key, so it is a backward-compatible change under the §4b additive-only rule.

7a. Google / Apple OAuth at the sign-up gate (PBI #1891)

A third way to sign in / up, alongside email+password (which is unchanged), on the same gate:

Method & route	Body	Returns
POST /v1/auth/oauth/{provider}	{ credential }	{ token, user } — the same JWT + account shape as /auth/login

• {provider} is google or apple. credential is the OIDC identity token the provider's browser SDK returns (Google's ID token / Apple's identity token); the backend validates it against the provider's published JWKS (issuer + audience + signature + expiry) before trusting any claim.
• Account resolution — all to the same uid model (an ExternalLogin row links (provider, subject) → an AppUser): a returning provider identity → its linked account; else a provider-verified email matching an existing account → link this provider to it (so Google and Apple for one person, or an OAuth sign-in after an email+password signup, land on one account); else a new password-less account is created and linked. Linking by email is only ever done for a provider-verified address.
• Enablement is per-deployment + surfaced in /v1/meta (googleOAuthEnabled / appleOAuthEnabled + the public googleOAuthClientId / appleOAuthClientId), so the SPA only shows a button the backend can verify. Config: BookTranslation:Auth:OAuth:GoogleClientId / AppleClientId (public values, not secrets); a provider with no client id is off and the endpoint 400s it. BookTranslation:Auth:OAuth:UseFakeVerifier wires a deterministic in-process verifier for dev/tests (the OAuth analogue of the Stripe/CoinPayments UseFakeGateway), so the whole flow is exercisable without real provider credentials.
• Errors: unsupported/disabled provider or missing credential → 400; an unverifiable token → 401; an existing but provider-unverified email → 409 email_taken (sign in with the password, then link).
• Go-live with real Google/Apple credentials is gated with the rest of real-money go-live (#1491), exactly as the real payment rails are — this PBI ships the flow + the fake-verifier-verified path.

8. Rate limits (PBI #2071)

The public API is metered per authenticated principal so a runaway or hostile client can't drain GPU budget or starve other tenants. Limits are keyed by the caller's uid — so a JWT (human) and an API key both resolve to the same budget, two keys for one account share it, and two accounts are isolated.

Tiers

All tiers are fixed-window (per minute) and config-driven per environment (defaults below; nothing is hardcoded). Normal interactive use — the SPA, a well-behaved agent — is never throttled.

Surface	Keyed by	Default	Config key (BookTranslation:RateLimits:…)
Authenticated default (the whole /v1 authed surface)	uid	300 / min	DefaultPerMinute
Billable processing (/projects/{id}/process, /process-next-batch)	uid	20 / min	BillableProcessingPerMinute
Status/event poll (…/status, …/events)	uid	120 / min	StatusPollPerMinute
Webhook management (/v1/webhooks…)	uid	30 / min	WebhookAdminPerMinute
Anonymous estimate (/v1/anonymous-estimate)	caller IP	10 / min	AnonymousEstimate:RateLimitPerMinute
Anonymous page image (picker thumbnails)	caller IP	600 / min	AnonymousEstimate:ImageRateLimitPerMinute

The billable tier is deliberately the tightest: each processing call can spend real GPU money. It is the coarse request quota that complements the wallet gate (402 insufficient_credit) — the wallet refuses work an account can't afford; this bounds the request rate on top, so a $0 or abusive account can't hammer the expensive path. An endpoint's own tier overrides the group default (the SignalR hub and the anonymous payment webhooks are mapped outside the authed group, so neither is throttled).

The 429 response

Exceeding a limit returns the same RFC 9457 envelope as every other error, with the stable code rate_limited, plus the standard back-off headers so a client / the MCP server can wait exactly long enough:

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Limit: 20
RateLimit-Remaining: 0
RateLimit-Reset: 12

{ "type":"https://kenly/errors/rate_limited", "title":"Too many requests",
  "status":429, "code":"rate_limited", "detail":"You have exceeded the request rate limit. …" }

Retry-After and RateLimit-Reset are seconds until the window resets.

Distribution + fail-open

Limiter state is held in Redis (the Aspire cache resource — the same Redis the idempotency store uses), so limits hold across every API instance. It fails open, mirroring the idempotency store: if Redis is unreachable the request is permitted rather than errored (rate-limit enforcement lapses for that request, availability does not), and a down Redis never blocks startup. With no Redis configured (a bare dotnet run or the tests) an in-memory counter with identical fixed-window semantics stands in.

Out of scope (here)

Full OAuth 2.0 / OIDC as a general authorization grant is a later option under #1356 — §7a covers identity-token sign-in only. This document covers the shape & safety of responses, not new transitions.