Multi-tenancy

ScaiKey is built around a three-level hierarchy: partners, tenants, and users. Every piece of data in the system belongs to exactly one tenant, and every tenant belongs to exactly one partner. This structure lets a single ScaiKey deployment serve many independent organizations with strict data isolation.

The hierarchy#

Partners are the top level. A partner represents a company or business unit that manages one or more tenants. Partners are typically created by ScaiKey super admins.

Tenants sit below partners. Each tenant is an isolated workspace with its own users, groups, applications, MFA policies, and custom attributes. Tenants cannot see or access each other's data.

Users belong to a single tenant. A user authenticates within the context of their tenant and can only access applications assigned to them within that tenant.

Tenant isolation#

Tenant isolation is enforced at every layer:

• Database queries are always scoped to a tenant ID.
• Tokens contain the tenant context. An access token issued for tenant A cannot be used to access tenant B resources.
• Admin API calls require the caller to have the right role for the target tenant.

Slug-based routing#

Each tenant has a unique slug. Auth-facing endpoints use the slug to determine tenant context:

1
2
3

/auth/tenants/{slug}/login
/auth/tenants/{slug}/register
/auth/tenants/{slug}/reset-password

When a user visits a tenant-specific URL, ScaiKey loads the correct branding, MFA policies, and identity providers for that tenant.

For API calls that are not slug-routed, the tenant context is set via a tenant_id parameter or inferred from the authenticated user's token.

Admin roles#

ScaiKey defines three admin role levels:

A super_admin can do everything. A partner_admin can manage the resources (users, groups, applications) of any tenant that belongs to their partner but cannot see tenants of other partners. Creating, updating, and deleting the tenants themselves is a super-admin action by default; a super-admin can delegate it to a partner's admins with the per-partner tenant self-management flag. A tenant_admin is limited to their own tenant. See Admin Roles and Permissions for the full permission matrix.

Role checks are enforced on every Admin API endpoint. Attempting to access a resource outside your scope returns a 403 error.

Tenant configuration#

Each tenant can independently configure:

• MFA policy (disabled, optional, or required).
• Password policy (minimum length, complexity requirements).
• Session lifetimes.
• Custom user attributes.
• Identity provider connections (LDAP, OIDC, SAML).
• Branding (logo, colors, custom CSS for login pages).

These settings are scoped to the tenant and do not affect other tenants, even within the same partner.

How a tenant reaches other ScaiLabs products#

A tenant is created once, in ScaiKey. It reaches a downstream product (ScaiGrid, ScaiDrive, …) not by being re-created there, but by assigning a user (or a mapped group) to that product's application — ScaiKey then syncs the user and their tenant to the app, which provisions the tenant on its own side. Do not call a downstream product's tenant-create endpoint by hand; that usually makes a duplicate. See Applications → Access, assignment, and provisioning for the trigger, the two sync paths, and the timing to allow when scripting.

What's next#

Read OAuth and OIDC to understand how tokens carry tenant context, or see Applications to learn about global vs tenant-scoped applications.