Application isolation
Every record is scoped to an app_id, enforced server-side from the authenticated principal.
Alongside mode, every record carries an app_id. All
reads and writes are scoped to the application that authenticated the request —
resolved from your credential, never from a parameter you
supply.
What this means for you
- You only ever see your own app's payments, invoices, refunds, and webhooks.
- There is no caller-supplied "act as app X" override on the app API. Scope is derived from the principal.
- Resource ids are only meaningful within your app; a
GET /payments/{id}for an id that belongs to another app returnsRESOURCE_NOT_FOUND, not the record.
Admin scope is different
Operators in the dashboard may have cross-app visibility, but even there access is governed by RBAC: a permission can be granted globally or scoped to specific apps. Cross-app search endpoints still narrow results to the apps the operator's grants cover.
Customer references are yours
customerReference (on payments and invoices) is your identifier for the
customer. The service stores and echoes it but never interprets it, so use whatever
key your system already has. It is the field you filter on with
GET /payments?customerReference=….