Business and tenant mapping

The tenant

A Business is the tenant. Every record a business owns carries its businessId, and every business route is /api/v1/businesses/{businessId}/…. The server resolves access from its own records only:

a person needs an ACTIVE BusinessMembership whose role holds the route's permission;
a business-bound token (OAuth or API key) must be bound to that exact business and hold the route's scope;
a client-credentials token needs an ACTIVE AppConnection between its application and that business; its effective scopes are the intersection of the token's and the connection's.

"Does not exist" and "not yours" return the same 404, so business IDs cannot be enumerated. IDs inside request bodies (variants, locations, customers, suppliers, accounts) are always re-checked against the business in the URL.

Sandbox and live never mix: sandbox applications reach only sandbox businesses and vice versa.

Mapping records

Mapping	Table	Key
Platform business ↔ POS business	`BusinessPlatformLink`	`(platformId, externalBusinessId)` unique; one link per platform per business
Platform user ↔ POS user	`FederatedIdentity`	`(platformId, externalUserId)` unique
Your record ↔ POS record	`ExternalMapping`	`(applicationId, businessId, entityType, externalId)` and `(…, internalId)` unique
App ↔ business grant	`AppConnection`	`(applicationId, businessId)` unique

ID cheat-sheet

Concept	POS field	Your side
Platform	`Platform.slug` (`rekadijo`)	your manifest `platform.id`
Business	`businessId`	`externalBusinessId`
User	`User.id`	`externalUserId`
Store / location	`locationId`	optional `locationId` on orders
Product / variant / category	`productId` / `variantId` / `categoryId`	`externalId` in sync payloads
Customer	`customerId`	`customer.externalId` on orders
Order	`Sale.id`, `Sale.number`	`externalRef`
Transaction	`Payment.id`	`payment.reference`

Resolving a business from your side

const link = await pos.platform.resolveBusiness(myBusiness.id); // platform:businesses
// link.businessId → use in every business route