Multi-tenancy guide¶

What scope identifiers mean — and what they do not prove.

Field map¶

Field	Where	What it scopes	Auth by itself?
`x-tenant-id` (header)	Fraud scoring + report delivery	Tenant-scoped data (e.g. blacklists); copied onto reports	No — still need valid `ApiKey` JWT
`tenant_id` (body)	Reconciliation	Which tenant’s GL/bank/session data is read/written	No — environment auth still required
`partner_id` (body)	Reconciliation	Partner organisation within/alongside tenant scope	No
`branch_id` (body, optional)	Reconciliation (some flows)	Branch narrowing (e.g. not_found reconcile)	No
`userId` / `user.user_id`	KYC; Fraud event payloads	End-customer identity for storage/lookup	No — not a platform tenant key

Every scoring call: Authorization: ApiKey <jwt> and x-tenant-id.
Tenant selects data partitions; JWT proves the calling backend identity.
A valid JWT with the wrong tenant still scopes to that tenant’s data — treat tenant as a trust boundary in your orchestrator.

No tenant header. Isolation between platform customers is an environment / programme agreement.
Inside a deployment, userId must be stable and unique per end customer — never reuse across people.

Always send tenant_id and partner_id on partner entry bodies.
Exception resolve scopes by partner + tenant + domain + cluster type (+ optional cluster ids).
Scope fields prevent cross-tenant writes only if callers are authenticated and authorised at the edge — they are not a substitute for credentials.

Claim	Reality
“I sent `tenant_id`, so I am authenticated”	False
“`userId` is a tenant”	False
“Same tenant string works on Fraud and Recon without mapping”	Not assumed — products do not share a universal tenancy bus
“`partner_id` authorises production ingress”	False