Developer guide

Persistence, authentication and multi-tenancy

2 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.

  • Multi-tenancy and data isolation — Every query carries the tenant it belongs to, applied at the storage layer. A Partner's queries only reach that Partner's users, wallets and operations.

  • Production OAuth and transport controls — Short-lived tokens, credential rotation, and transport controls — TLS, allowed origins and request limits — for a deployment reachable from the internet.