Copy page

Concepts

Test mode

Test mode is on in production since dashboard v2 (2026-10-08), for a narrow set of operations. Two operator switches gate it, and both are on: api_v1.test_mode (every sk_test_ call) and api_v1.test_mode_forwarding (the calls that run in the development project). A sk_test_ key reaches only the operations the coverage table below marks full or sandbox, within what a business key may call: API-key, request-log and account reads on the test twin account, and webhook endpoints, webhook deliveries and the per-object event lists in the development project. Every other operation a business key may call answers it 503 temporarily_unavailable — payment links, subscriptions, payouts, payroll, the wallet, quotes, orders, customers and capabilities included. If either switch is turned off, the operations it gates answer 503 temporarily_unavailable again. Four operations enforce the refusal a second time, in their own handler code, independent of the platform-wide gate — quotes.create, quotes.get, orders.create and customers.create — each answering 503 temporarily_unavailable before contacting any provider, releasing the idempotency reservation since nothing was dispatched. Every /v1 projection echoes the reading key's mode: no route projection hardcodes livemode: true (the last two, customer and payment, were fixed in A4F-DOCS), and test_mode.test.ts fails if one ever does again: that source scan over api-v1/routes is the G7 guard. A separate walk in test_mode_inbound.test.ts proves only that the DEV mirror principal answers livemode: false; it runs a stub handler, not the real forwarded routes, and a projection test over those handlers is still open. The order and customer event payloads take the account's mode when they are emitted.

How the mode is selected

The fork is never the key prefix — it is caller.livemode, an accounts.livemode column resolved once at auth and never re-read from a header or a body field. A live caller is completely untouched by anything on this page; the routing below exists only on the livemode=false path.

• sk_live_… → the caller's live account, production, live providers — no change, ever.
• sk_test_… → the caller's test twin account (acct_test…, linked from the live account by accounts.test_twin_account_id, created implicitly the first time POST /v1/api_keys is called with livemode: false) — then one of three things below, decided per operation.

What happens on a test-mode call

Every gate that already runs for a live caller — the account's own rate limit, kill switches, scopes, idempotency reservation — runs identically first, for every caller. The fork is the very last step, and it resolves to exactly one of three dispositions, set on every route in api-v1/router.ts's table (AuthenticatedRoute.testMode, required, no default — a route with none of the three values fails to compile):

• local — the same handler runs in production, scoped to the test twin account. No provider is in the loop, so there is nothing to forward. Exactly nine operations run this way: the developer operations api_keys.* and request_logs.list (credentials and the outer usage log are prod-only by design), plus account.get and accounts.list, which read the test twin account itself. A signed-in session in test mode lists only its test twins, never its live accounts. Their market comes only from the twin's declared country or the default, never from the owner's verification data. An sk_test_ key resolves the twin's owner, who is the live account holder, and reads exactly one user-level field of theirs: email, the owner's login email, the same in both modes. Treat an sk_test_ key as able to read that email. The other user-level fields are withheld from a test key and replaced by defaults, so the shape matches live: language and support_contact are null, notification_preferences is {marketing: false, product_tips: true} and dashboard_preferences is {}. They are never the owner's values. caller describes the credential, not the owner, so it is published in both modes: {credential: business_key, role: null} for a key. A signed-in session in test mode is the owner themself and sees its own values. account.update, accounts.create and the two waitlists are refused: they write live account state. account.update also refuses, in its handler, any user-level field (language, preferences, support contact) from a test caller with 400 livemode_boundary before any write. accounts.create also refuses a test caller in its handler (503, sideEffectFree), because a new account is always live. A test caller therefore never reaches the one-account-per-login 409 account_already_exists a live caller gets.
• forward — the request runs in the sandbox environment over a signed, single-use hop. The hop carries only the request itself and an opaque account id: never the caller's key, never a service-role credential, never the caller's IP address or user agent. The signature covers the method, path, query string and Idempotency-Key, and a request that differs from the signed values is refused. In the sandbox the handler runs against the Bridge sandbox where it calls Bridge. The contract also defines a fixtures value for a provider with no sandbox, but no fixture exists in code today: neither fixtures operation is routed, so nothing answers with one. Production passes through only an answer the sandbox executor produced. Anything else becomes 503 temporarily_unavailable with Retry-After: 60; it is marked sideEffectFree only for a read, and no platform body is ever shown.
• refused — 503 temporarily_unavailable, sideEffectFree: true, before any handler runs. The four operations named above earn this the honest way, in their own code; credit_checkouts. create earns it by design (below); every other operation whose contract value is unavailable is refused by its route too. So every operation the contract marks unavailable answers 503 temporarily_unavailable even with api_v1.test_mode on. Router and contract are tied by the strict parity test in supabase/functions/api-v1/__tests__/test_mode.test.ts: a route whose disposition differs from its contract value fails CI, with no exception list.

These guards stand between a test caller and live money. Each has its own test, none needs the network, and they are layered rather than independent: most act only once an earlier one has let the request through.

• G1, the fork. A live caller is never forwarded and a test caller never reaches a live handler; swept over every route in the router's table (test_mode.test.ts).
• Prod-side second guard (A4F-M2). On production a test caller can run only the routes in LOCAL_ALLOWLIST; every other handler refuses it before any money or owner lookup (test_mode.test.ts, "A4F-M2").
• G2, the destination. The DEV project ref is a literal; a hop that would loop back to itself is refused (test_mode.test.ts).
• Sandbox posture is asserted before any provider call. The sandbox refuses to execute a hop unless its process-wide sandbox switch is on, every provider switch reads sandbox and no live-network setting is present; production refuses a request that already carries hop credentials; a live-mode assertion is refused in the sandbox. A live provider host is never a valid target for a test-mode request; the internal evidence for each of these guards lives with the engineering notes, not on this page.
• Projections never claim live mode for a test caller (see the top of this page).

Test mode settles Tempo only on the tempo-moderato testnet: activating a payment link whose settlement destination is on tempo-mainnet is refused 422 settlement_rail_unsupported. Any operation whose response carries funding or deposit instructions is unavailable in test mode, and test_mode.test.ts fails if one is restored. Payout funding instructions already carry sandbox: true next to their chain for a test caller, so a sandbox address is labelled as one.

Hosted pages

The payer page a payment link's url points to depends on the project that holds the link. A test-mode link lives in DEV, so on DEV its url is https://staging.swaps.app/pay/<token> (the dashboard build on the DEV backend), for a test key and a live key alike. Production keeps https://swaps.app/pay/<token> for a live key; a test key on production has no page, so url is null. The host is per-environment configuration (see Environments), never a literal in the code: while a project has no host configured, url is null rather than a guessed address, and DEV never publishes a swaps.app production URL where the token would 404. paymentLinkPublicUrl (supabase/functions/api-v1/routes/payment_links_shared.ts, tests in routes_payment_links_shared.test.ts and routes_payment_links.test.ts) decides this. payment_links.create is unavailable in test mode today, so the router refuses it before this code runs.

No outbound email

Test mode sends no email to anyone. The shared sender refuses every send made inside a test-mode dispatch and every .invalid recipient (each test twin's synthetic principal is test-acct_…@sandbox.invalid); the invoice email, the payment-link reminder and payer-nudge sweeps and payout notifications skip any row whose owner is a test twin's principal; the lifecycle and broadcast audiences exclude those principals. payment_links.send_invoice stays refused in test mode: the response has no field that could say the email was not delivered. Evidence and tests: docs/api/TEST-MODE-PROVIDERS.md §13.

No time-driven firing

No operation is dev-cron today — the bundled contract carries zero x-swaps-test-mode: dev-cron values (corrected from a stale "three operations" claim, K11-6 fixer round 1, finding #6/#11). The category is specified for a future payment-link-reminder / payroll-funding-poll build, but nothing has claimed it yet. The DEV cron jobs themselves do run: a read-only check of DEV's cron.job on 2026-09-24 found payment-links-cron (every 15 minutes), payout-notifications, crypto-subscriptions-emitter and the sandbox webhook worker active, and DEV holds a Resend key. None of them emails anyone for a test twin's rows (see "No outbound email" above), and no contract value promises that a schedule fires for a test object (design decision D-3).

webhook_endpoints.*/webhook_deliveries.* being sandbox (routing only) is not the same claim as delivery firing: a queued delivery is only actually sent by DEV's own sandbox webhook worker cron job (migration 20260905120000, scheduled every minute) while DEV's api_v1.webhooks_delivery flag is on. Both were on in DEV's read-only state of 2026-09-24 (TEST-MODE-PROVIDERS.md §13); no test proves an end-to-end test-mode delivery yet.

Other git-tracked cron jobs could act on test rows in DEV: payment-links-cron (reminders), crypto-subscriptions-emitter, payout-notifications and lifecycle-notify. Whether each is scheduled on DEV has not been verified either. It does not matter for a test caller today, because every operation that creates a row those jobs read is refused.

Credits

credit_checkouts.create is unavailable in test mode, not sandbox — it opens a real Stripe payment for a credit pack, and there is no test purchase to substitute (design decision D-4, pending the founder's sign-off on whether one should exist). credits.get/credit_events.list are ALSO unavailable in the bundled contract today (corrected from a stale "Stripe test mode" source description, finding #6) — no sandbox claim has been restored for either read yet, so both still answer the platform-wide 503 once forwarding is on, same as the checkout itself.

Coverage by resource

Of the 164 routed operations, 9 are local, 15 are forward and 140 are refused. Each route's disposition is exactly its contract value (full → local, sandbox → forward, unavailable → refused), checked operation by operation in test_mode.test.ts. The 24 reachable operations are exactly test-mode-truth.test.ts's evidence list.

Test-mode events: GET /v1/events/stream is refused and never forwarded, because production could not re-check a revoked sk_test_ key on every tick of a stream it only relays; GET /v1/events and GET /v1/events/{id} are unavailable too. Test-mode events are not readable through /v1 today — no test object can be created yet; once creates are restored, poll the forwarded per-object */events lists (GET /v1/payouts/{id}/events and its siblings). DEV writes no event at all until DEV's api_v1.events flag is on; turning it on is an operator step on DEV only, a prerequisite for webhook test events and replays there, and no production flag changes.

Test mode	Router disposition	What it means	Example resources
full	local	No provider in the loop — the same handler, in production, on the test twin account	9: api_keys.*, request_logs.list, account.get, accounts.list
sandbox	forward	A real Bridge sandbox call, made by the DEV project	15: webhook_endpoints.*/webhook_deliveries.*, the five *.events.list reads (payments, payment_links, payouts, payroll, orders)
fixtures	forward	Reserved for a provider with no sandbox. No fixture exists in code today	Specified (screenings.reports.evidence_pdf.get, payment_sessions.pay_with_wallet) but neither is routed yet — no fixtures operation is reachable today
dev-cron	forward	The object is readable and writable in DEV; nothing fires on a schedule (see above)	None — no operation currently claims this value (see above)
unavailable	refused	503 before any handler runs — either the operation itself refuses test mode (four operations, plus credit_checkouts.create), or K11 has not yet individually evidenced a claim for it	140: quotes.create, orders.create, credit_checkouts.create, customers.create, capabilities.get, events.*, account.update, accounts.create, virtual_accounts.* reads, every payout, payroll, payment-link and wallet write (including payroll_runs.items.reissue_link), and every other operation not on test-mode-truth.test.ts's evidence list

unavailable on an operation not in that evidence list is not a claim about the operation's own code — it is A1-3's annotation freeze, meaning only that K11 has not restored a specific full/sandbox/fixtures/dev-cron claim for it yet, each restoration landing with its own test (test-mode-truth.test.ts's K11_EVIDENCE_LIST). The router dispositions every such route as refused, so it answers 503 whether api_v1.test_mode is on or off. Each operation in the reference states its own x-swaps-test-mode value — read it there rather than assuming from this table.

What test mode's build already proves, mechanically (not "is designed to" — CI runs this)

• A live caller is never forwarded, and a test caller never reaches a live handler — swept over every route in the router's own table, not asserted by discipline.
• A blocked live-provider call is reported as 503 live_provider_blocked, not as an internal error; there is no fixture to fall back to.
• No caller credential and no service-role key ever crosses the hop. The signed assertion carries an account id, a role and scopes already checked in production, and a nonce. The request itself crosses too; see "Test data" below.

Test data

What a forwarded test-mode request sends to DEV, as the code stands today (test_mode.ts):

• the signed assertion: v, iss, livemode, account_id, account_public_id, caller_kind, role, scopes, plan, method, path, query, operation, swaps_version, request_id, idempotency_key, ts and nonce;
• the query string and, for a write only, the request body, byte for byte;
• headers: the caller's x-correlation-id and cf-ray as sent; x-request-id, which is the caller's own x-request-id or x-client-request-id (at most 128 characters) or else a fresh id from production; the caller's Idempotency-Key when sent; and, for a write, the caller's content type (application/json when none is sent). Production adds the assertion, its signature and Swaps-Version. No other caller header crosses.

DEV records no client IP for a forwarded request: its usage-log row is written with the IP left empty (test_mode_inbound.ts), because the hop arrives from production, not from the caller.

Where it is stored: the Swaps development project, which is not production. Rows a forwarded request writes there (for example a webhook endpoint, a usage-log row, an idempotency record) have no retention window and nothing deletes them automatically. They are deleted on request: an operator erases the account's test-mode data, which removes the account's test webhook endpoints and deliveries, events, usage-log and idempotency rows, its sandbox principal and the test account itself (API-CANON §15). Do not submit real personal or bank data in test mode. Use made-up names, addresses and account numbers.

What test mode does not do

• It does not simulate every failure mode a live provider can produce — sandboxes and fixtures cover the happy path and the documented error cases, not every edge case a live integration might hit.
• It does not fire anything on a schedule yet (see "No time-driven firing" above) — a dev-cron claim describes an object's shape, not a running job.
• There is no separate OAuth agent-token class — that claim was withdrawn (decision C4-D32, see Authentication & keys). An agent authenticates with a business key, which already carries its own test/live split (sk_test_…/sk_live_…), so this is not a gap.

Next: Get started walks the whole loop end to end · Conventions for the shared rules every resource follows.