Tenant Isolation

Enforcing clear boundaries between tenants is critical in multi-tenant systems. Wristband ensures all tenant-specific data is logically isolated, sandboxing operations to eliminate cross-tenant side effects. The following sections explore how Wristband's entity model and authentication workflows are architected to maintain strict isolation boundaries.

Entity Model and Data Scoping

Tenants are first-class entities in the Wristband architecture. After setting up a Wristband application, your first step is provisioning individual tenants. Any subsequent sub-entities you create inherit strict, logical isolation boundaries specific to that tenant. This architecture allows you to manage resources freely without risking cross-tenant conflicts. For example, two completely separate users can share the same email address, provided they reside in different tenants.

Duplicate user emails across tenants — Figure 1: Model showing users with the same email address co-existing in different tenants.

Conversely, creating duplicate email addresses within the same tenant and identity provider (IdP) is restricted. Wristband enforces strict email uniqueness constraints within each localized tenant-IdP boundary to maintain data integrity.

Duplicate user emails in same tenant — Figure 2: Two users with duplicate emails can't exist under the same tenant and IdP.

Importantly, duplicate email addresses are permitted within a single tenant if the users utilize different identity providers (IdPs). This flexibility exists because user identity in Wristband is scoped by both the tenant and the respective IdP.

Duplicate user email in same tenant but different IdPs — Figure 3: Two users can exist under the same tenant with duplicate emails if they belong to different IdPs.

In addition to users, you can create the following entities under a single tenant:

Identity Providers (IdPs): Identity Providers (IdPs) authenticate users and issue secure identity assertions to external applications. In a multi-tenant context, tenant-scoped IdPs are typically enterprise platforms like Okta or Microsoft Entra ID used to facilitate Single Sign-On (SSO).
Roles: Roles are collections of permissions assigned to users or clients to authorize actions within your application. In Wristband, roles are tenant-scoped, allowing each tenant to define and manage their own unique set of access controls.
Machine-To-Machine Clients: Machine-to-machine (M2M) clients grant tenants secure, programmatic access to your application's APIs. These dedicated client credentials allow tenant systems to automate workflows and query endpoints independently.

Authentication and Session Isolation

Tenant isolation profoundly impacts user authentication design. In multi-tenant environments, a unified, global login page falls short because individual tenants demand unique authentication experiences. Furthermore, since distinct users can share identical login identifiers (like email addresses) across different tenants, the authentication mechanism must incorporate a tenant identifier to accurately resolve and authenticate the user.

To meet these requirements, Wristband provisions dedicated login pages for every tenant. Users initiate authentication by navigating directly to their tenant's localized login page, hosted on a globally unique vanity domain. Once credentials are submitted, Wristband scopes the authentication request exclusively against the user directory bound to that specific tenant.

Figure 4. Illustration showing how each tenant has its own login page for authenticating its users. — Figure 4: Illustration showing how each tenant has its own login page for authenticating its users.

Because users may not always remember their specific tenant, Wristband provides an application-level login flow to assist with tenant discovery. Users access this centralized interface via your primary application vanity domain. Upon arrival, the interface dynamically presents a discovery screen based on your configured tenant discovery strategy. Wristband supports the following tenant discovery methods:

Email Resolution: Users enter their email address to receive an access link or a one-time password (OTP), based on your verification settings. Completing this step reveals a dashboard listing all tenants associated with that identity, allowing the user to select and jump to their desired workspace.
Tenant Name Resolution: Users enter their tenant's unique name to trigger an immediate redirect to their specific tenant login page. This flow is useful for users who know their organization's identifier.
Email Domain Mapping: Users enter their email; the domain is parsed from the email, and based on configured email domain mappings, they are routed to the correct tenant.

To optimize the application login flow, Wristband can track and remember a user's previously accessed tenants. When this feature is active, returning users are greeted with a personalized dashboard listing their recently used tenants. They can then select a tenant to skip discovery and go straight to the tenant's login screen.

Figure 5. Illustration showing the application login page with 'Remember tenants' enabled. — Figure 5: Illustration showing the application login page with 'Remember tenants' enabled.

Upon successful authentication, Wristband issues a secure session cookie to persist the user's state. To preserve strict isolation, these cookies are scoped exclusively to each tenant's unique vanity domain, preventing cross-tenant session interference. This architecture enables seamless context-switching for individuals managing multiple tenants without forcing them to re-authenticate.

Figure 6. Illustration showing how Wristband auth session cookies are associated with tenant vanity domains. — Figure 6: Illustration showing how Wristband auth session cookies are associated with tenant vanity domains, allowing users to be simultaneously logged in to multiple tenants.