Developer guide

Persistence, authentication and multi-tenancy

3 min read

Tenant isolation

Every tenant-owned record carries tenant_id; application repositories require tenant context. Tenant isolation uses PostgreSQL row-level security with transaction-local tenant context, so normal application roles cannot bypass the boundary.

Source of financial truth

PostgreSQL holds the operation journal, audit data, ledger and messaging records. Caches and read projections may be rebuilt and are never the only financial truth.

Atomic transitions

Operation creation, reservations and outbox events belong to one logical transaction. The same principle applies to deduplication, state transitions, final postings and reservation adjustments.

Persistence layer

PostgreSQL migrations and snapshots keep the schema and durable state versioned and reproducible. See Fees, ledger and reconciliation for the ledger boundary.

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

  • PostgreSQL, migrations and snapshots — State is stored in PostgreSQL and every schema change is a versioned migration applied in order. A database can be rebuilt from scratch by running them.

  • Initial idempotency and outbox — Each operation carries an idempotency key. If the same request arrives again, the API returns the result of the first one instead of creating a second operation.

  • Simplified OAuth for Sandbox — The Sandbox authenticates against the API with client credentials and obtains a token, with the same request and answer shape as the production flow.

  • Fully relational financial persistence — Balances, reservations and ledger entries are stored as tables with keys and constraints, so the database itself rejects a negative balance or a reservation with no operation behind it.

  • One deployment per Partner — A Partner gets its own instance, its own database and its own secrets. Isolation is the boundary of the deployment rather than a column in a shared table, so nothing another Partner runs can reach its data.

  • Several Partners inside one instance — Every query carries the tenant it belongs to, applied at the storage layer with row-level security. A Partner's queries only reach that Partner's users, wallets and operations, even when the rows sit in the same tables.

  • Production authentication between systems — A caller proves who it is with a signed assertion instead of sending a shared secret: one key per client, named by its identifier so it can be rotated on its own, and an assertion that cannot be replayed. Tokens are short-lived and the registry of clients survives a restart.

  • Workload-to-workload authentication and gateway mTLS — Each service proves its own identity to the next one, and the channel to the signer gateway is authenticated on both ends. Reaching the gateway from inside the network stops being enough to ask it for a signature.