Most B2B SaaS apps are multi-tenant: each customer (a tenant) gets their own workspace, users, and permissions. Authaz handles tenant isolation natively, so you don't write the row-level filters yourself.
Pick a tenancy model when you create the application:
application
└── users (one pool)
└── memberships → tenant A, tenant B, tenant C
Users live in a single pool but are members of one or more tenants. Roles are scoped per tenant: a user can be Admin in Acme Corp and Viewer in Initech. The same email signs into both.
Right for: products where users move between workspaces and you want them to keep a single identity across tenants.
application
├── tenant A → users pool A (cannot see B)
├── tenant B → users pool B (cannot see A)
└── tenant C → users pool C (cannot see A or B)
Each tenant gets a fully separate user pool. A user in tenant A cannot exist in tenant B unless they sign up again. Maximum isolation.
Right for: healthcare, finance, government, or anything where tenants must not share even the existence of an identity.
The user-pool layout is one decision; what each tenant can customize (branding, email templates, email provider, the entire auth stack) is a separate set of switches under Settings → General → Tenant Customization. See Tenancy Customization — that's the page that turns the abstract tenancy model into concrete per-tenant editable surfaces.
Most management endpoints have a tenant-scoped variant. The path tells the story:
Operation
App-scoped
Tenant-scoped
List users
GET /v1/users
GET /v1/applications/{appId}/tenants/{tenantId}/users
Send invitation
POST /v1/invitations
POST /v1/applications/{appId}/tenants/{tenantId}/invitations
Assign a role
POST /v1/role-assignments
POST /v1/applications/{appId}/tenants/{tenantId}/role-assignments
List sessions
GET /v1/sessions
scoped via the user's token tenant
The path prefix is the contract — you'll never see a ?tenantId=... query parameter, and you never have to remember to add a filter clause manually.
Tenant scope can also come from the caller's identity: if you call a non-tenant-scoped path with a Bearer token whose tenant_id claim is set, Authaz auto-scopes responses to that tenant. This is what powers your end-customers' self-service admin pages — same endpoints, narrower view.
When a user belongs to multiple tenants in the shared-pool model, Universal Login shows a tenant picker after authentication. The selected tenant is recorded in the access token:
Your backend reads tenant_id straight from the JWT. No extra round-trip.
You can also force a specific tenant at the start of the OAuth flow by adding &tenant_id=... to the authorize URL — useful for tenant-on-subdomain setups.
