Tenants are secondary owners of a Multi-Tenant Account (MTA). A tenant holds the same permissions as the primary account holder on that customer account. Each tenant must already be an onboarded zerohash participant and must be different from the primary account holder.
Use these endpoints to grant or revoke a participant's shared ownership of a customer account. Both operations are asynchronous - they return 202 Accepted with an empty body, and the change is applied in the background.
All endpoints use standard zerohash API-key authentication (a signed Signature and Timestamp).
Endpoints
Add tenant
POST /accounts/{zrn}/tenants
Adds a tenant to an existing customer account.
- Path —
zrn: the customer account's ZRN, in the formatzrn:zh:<region>:account:customer:<uuid>. - Body —
participant_code(required): the 1–6 character participant code of the tenant to add (e.g.PART01). - Response —
202 Accepted; the tenant is added asynchronously.
Remove tenant
DELETE /accounts/{zrn}/tenants/{tenant}
Removes a tenant from an existing customer account.
- Path -
zrn: the customer account's ZRN (same format as above). - Path -
tenant: the 6-character participant code of the tenant to remove (e.g.PLAT01). - Response -
202 Accepted; the tenant is removed asynchronously.
Good to know
- Same permissions - A tenant can act on the account just like the primary holder, so add tenants deliberately.
- Must be onboarded - The participant being added must already exist on zerohash and cannot be the primary account holder.
- Asynchronous - A
202means the request was accepted, not that the change is live yet. Confirm via account details or the relevant account webhook before relying on the new tenant set.