Persistence, authentication and multi-tenancy

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.

• Idempotency keys on every operation — 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.

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

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