Tenancy and scopes

Every organisation on the platform is a tenant. An insurer is a tenant, a broker is a tenant, and a distribution channel is a tenant. They are the same kind of object and they are told apart by what they are permitted to do, not by which system they live in.

This matters to an integration because it decides two things: which records a call can reach, and which calls a credential is allowed to make.

One tenant owns every record

Each record belongs to exactly one tenant. There is no shared pool that several organisations read from, and no record that belongs to two tenants at once.

Where two organisations both have an interest in the same event, they hold separate records of it and each record belongs to one of them. A claim on a policy an insurer underwrote and a broker placed is one claim to the customer and two records on the platform. This is the reason a broker cannot see a carrier’s book by asking for it in a different way. The separation is in the data model rather than in a filter applied on the way out.

Scopes are granted per tenant

Access is granted as scopes, and a scope is held by a tenant rather than by a person. A credential carries the scopes of the tenant it belongs to, so what a call may do is settled before anyone authenticates as an individual.

Each tenant has its own catalogue of scopes. Two insurers on the platform do not necessarily hold the same set, because what a tenant is entitled to do follows from its contract.

The catalogue lives in the Singapore control plane alongside identity and tenancy. That is a deliberate split: the control plane knows who a caller is and what they may do, and it holds no personal data at all. Whose data it is and where that data sits is a regional question.

Note

The scope names your credentials carry are issued with those credentials rather than listed here. That is a property of the model rather than an omission: a scope catalogue is a description of who else is on the platform and what they may reach, and the platform carries competing distributors and competing carriers at the same time.

So which string do you send? The one issued to you, always. The standard names two scope classes, a read and a write, and those two names describe the division rather than the literal you put on the wire. Every module page that says an endpoint needs admin means the write scope your credentials carry. Send what you were issued and read the module pages for which of the two an endpoint needs.

What the standard settles

Authentication is not a platform invention. OAuth 2.0 bearer tokens, the error shape, the pagination form and the idempotency header are all settled by the standard, and the platform implements them rather than restating them here. They are in the standard’s API conventions.

The platform adds one thing on top: an Idempotency-Key is honoured for seven days. Keep the key for at least that long. A replay after the window creates a new resource instead of matching the original, because deduplication state is not kept forever.

The base URL works the same way as the scopes. The standard fixes everything from /v1 onward, so the paths in the module pages are the paths you call. The host in front of them is per tenant and per market, because coverage runs once per market, and it reaches you with your credentials rather than from a page here.