Tenants and members¶
A tenant is one customer workspace. Everything the API stores belongs to exactly one tenant, and every request acts in exactly one. Inside a tenant, retailers are the businesses whose orders are handled.
Roles¶
Tenant roles are owner, admin and member. People get a role through an invitation. Teams (groups) only organize
people; membership and role decide access.
| Role | Permissions |
|---|---|
owner, admin |
Everything in the tenant: read and write orders, products, cases and evidence; shipping labels and rates; manage retailers, provider accounts (shops) and members |
member |
Read orders and products, compliance cases and shipping |
A member therefore cannot call operations that need providers:manage, such as retailers, tenantMembers or
createRetailer. They get FORBIDDEN.
Retailer access¶
A person with no retailer grants can act for every retailer in the tenant. Granting specific retailers narrows what that person sees, but it is not an isolation boundary. Exactly:
- List queries narrow to the granted retailers.
- Single-item reads of orders (
order(id)) and compliance cases are tenant-wide: the id alone is enough. - Retailer management (
retailers,retailer(id),archiveRetailer) is tenant-wide for owners and admins. - Orders that belong to no retailer pass every scope.
- Products and shipping zones and rules answer
NOT_FOUNDfor another retailer's id, so those ids are not confirmed. - Shipping labels and provider accounts answer
FORBIDDENfor another retailer's.
Do not rely on grants to keep one retailer's data from another retailer's users in the same tenant; use separate tenants
for that. Grant access with grantRetailerAccess(retailerId, actorId); a retailer's members field lists the actor ids
it is granted to.
Who creates tenants¶
Users cannot create tenants. Riotbyte creates a tenant and invites its first owner; that owner then invites everyone else. If you need a tenant, ask Riotbyte.
Choose the tenant a session acts in¶
A session acts in its active tenant. List the tenants you belong to, then activate one:
API=https://<your ecomtaxfree host>
curl -sS -b cookies.txt "$API/api/auth/organization/list"
curl -sS -b cookies.txt -X POST "$API/api/auth/organization/set-active" \
-H 'content-type: application/json' -H "origin: $API" \
-d '{"organizationId": "<tenantId>"}'
The ids in the list are tenant ids. The web app does the same on sign-in: it activates the invited tenant, else the
tenant the session already has, else the first in the list. Accepting an invitation already activates that tenant, so
set-active is only needed to switch later.
On GraphQL requests you may send x-tenant-id to say which tenant you believe you are acting in. For a session the
header can only confirm the active tenant, never change it:
| Situation | Answer |
|---|---|
| No active tenant | TENANT_REQUIRED |
| Active tenant, but you are no longer a member | TENANT_REQUIRED |
x-tenant-id differs from the active tenant, or is not an id |
TENANT_MISMATCH, with activeTenantId in the error's extensions |
{
"errors": [
{
"message": "The requested tenant is not the session tenant",
"extensions": {
"code": "TENANT_MISMATCH",
"activeTenantId": "<tenantId>"
}
}
]
}
Sending x-tenant-id on every request is worthwhile: if another tab or process switches the session's tenant, your next
request fails loudly with TENANT_MISMATCH instead of silently reading the wrong workspace. Switch tenants with
set-active, then retry.
Invite someone¶
Owners and admins invite by email:
curl -sS -b cookies.txt -X POST "$API/api/auth/organization/invite-member" \
-H 'content-type: application/json' -H "origin: $API" \
-d '{
"email": "[email protected]",
"role": "member",
"organizationId": "<tenantId>"
}'
The answer contains the invitation id. The platform emails the invitation, which expires after 7 days by default. The
link in the app's Settings access page signs in someone who already has an account; a new person must sign up from the
email, because only the email carries the inbox token.
List the tenant's invitations with GET /api/auth/organization/list-invitations. Only owners and admins see them; a
member gets 403.
Accept an invitation¶
After signing in (or signing up, see Authentication), accept:
curl -sS -b cookies.txt -X POST "$API/api/auth/organization/accept-invitation" \
-H 'content-type: application/json' -H "origin: $API" \
-d '{"invitationId": "<invitationId>"}'
Accepting needs a verified email, which signing up through the invitation provides.
Accepting activates the tenant for your session. Use set-active later to switch between tenants.
List members¶
Through GraphQL, owners and admins can list the people in the active tenant:
query TenantMembers {
tenantMembers {
actorId
name
email
}
}
Roles come from Better Auth's organization endpoints, which the web app reads when it shows the members list.
Teams¶
The web app also manages teams (groups) through Better Auth's organization endpoints. Teams only group people, they carry no permissions of their own.