Skip to content

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_FOUND for another retailer's id, so those ids are not confirmed.
  • Shipping labels and provider accounts answer FORBIDDEN for 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.