Tenant Discovery

For multi-tenant applications, user login is a two-phase process. Tenant discovery is the first phase, performed on the Application-level Login Page. The goal is to find the Tenant-level Login Page that the user needs to authenticate on.

Workflow Policies

The Tenant Discovery workflow helps users identify which tenant they belong to before being redirected to their tenant-level login page. Several policies control how users discover their tenant and how Wristband verifies their identity during the process.

Tenant Discovery policies are configured under Workflow Policies in the Application View of the Wristband Dashboard.

Remember Tenants: Controls whether the tenants that a user has previously authenticated into are remembered for future discovery flows. This is disabled by default.
Enabled Discovery Strategies: Controls which discovery strategies are available to users: both email address and tenant name, email address only, or tenant name only. The default has both strategies enabled.
Default Discovery Strategy: When both discovery strategies are enabled, controls which is presented first: email address or tenant name. The default is email address.
Email Verification Strategy: When email-based discovery is used, controls whether the tenant discovery email contains a verification link or a one-time code. The default is verification link.

Tenant Discovery Workflow Policies in the Wristband Dashboard

How to Discover Tenants

There are two ways a user can find their Tenant-level Login Page from the Application-level Login Page:

Entering their email address for a more consumer-like experience
Entering their tenant name for a direct path to their Tenant-level Login Page

The enabled discovery strategy policy controls which strategies are available to users. By default, users can choose either strategy, and a toggle link allows them to switch between strategies. The default discovery strategy policy controls which is shown first.

ℹ️
Note: If you restrict users to a single strategy, no toggle link appears in the UI.

ℹ️
Note: If application-level signup is disabled in Application Settings, the signup link will not appear on the Application-level Login Page.

Enter Email Screen — Application-level Login Page showing email-based discovery with the option to switch to tenant name strategy.

Using an Email Address

When a user enters their email address, the experience differs based on how many tenants they belong to across your application.

Application-level Login Page showing email-only discovery with no option to switch to tenant name strategy.

If the user belongs to only one tenant, they are automatically redirected to that Tenant-level Login Page.

If the user belongs to two or more tenants, Wristband sends a Tenant Discovery email to the provided address. What happens next depends on the email verification strategy policy:

Verification Link: The user clicks the action link in the email, which opens a new tab and takes them directly to the Tenant Selection Page where they can select which tenant to log into.
One-Time Code: The login form changes to display a one-time code input field. The user enters the code from the email, and the Tenant Discovery Page is then shown inline with the list of tenants to choose from.

Tenant Discovery Page — Tenant Selection Page showing the list of tenants a user belongs to, displayed after clicking the action link in the Tenant Discovery email.

Using a Tenant Name

If the user enters their tenant name directly, they are redirected straight to that tenant's login page without needing to go through email-based discovery. If your Login Endpoint uses tenant subdomains, then the input field displays the remainder of the vanity domain as a suffix to help users understand what to enter.

Enter Tenant Domain Screen — Application-level Login Page showing tenant name-only discovery with no option to switch to email strategy.

Remembered Tenants

If the Remember Tenants policy is enabled, tenants a user has previously authenticated into are remembered for future discovery flows, reducing the need to re-enter their email or tenant name on subsequent visits. Remembered tenants persist until the user explicitly removes them by clicking the Remove link displayed under each tenant option on the Application-level Login Page.

Application-level Login URL

The Application-level Login Page is where Tenant Discovery takes place. Users arrive here first to identify their tenant before being redirected to their Tenant-level Login Page. There are publicly available URLs where you can reach the Wristband-hosted Application-level Login Page for multi-tenant applications.

Wristband Vanity Domains

Let's say we had a Wristband application named yourapp. The application-level login URL would look like the following:

https://yourapp-yourcompany.us.wristband.dev/login

Custom Domains

If you had the custom domain auth.yourapp.io enabled for your application, the login URLs would look something like the following:

https://auth.yourapp.io/login

Supported Query Parameters

The URLs for the Wristband-hosted Application-level Login Page can support certain query params that will be processed and utilized by the Wristband platform. You can use the following query params for enhanced functionality:

Query Parameter Description

client_id If your application accommodates multiple OAuth2 clients for authentication, you can precisely designate the login URL that Wristband redirects to at the end of the signup process. This is achieved by specifying the clientId associated with the desired OAuth2 Client whose login URL you intend to utilize. To ensure the continuity of this feature, include the client_id query parameter when navigating to the Application-level Login Page. Wristband will automatically incorporate this query parameter into the Signup URL found in the Signup Action Link at the bottom of the login form (if Signup is enabled).

Query Parameter	Description
`client_id`	If your application accommodates multiple OAuth2 clients for authentication, you can precisely designate the login URL that Wristband redirects to at the end of the signup process. This is achieved by specifying the clientId associated with the desired OAuth2 Client whose login URL you intend to utilize. To ensure the continuity of this feature, include the `client_id` query parameter when navigating to the Application-level Login Page. Wristband will automatically incorporate this query parameter into the Signup URL found in the Signup Action Link at the bottom of the login form (if Signup is enabled).

Tenant Discovery Email Domains

You can configure allowed email domains to control which tenants appear in discovery results when a user enters their email address. When a user's email domain matches a configured domain, that tenant will appear as an option, even if the user doesn't yet exist in that tenant. This is configured per tenant under Tenant Settings in the Tenant View of the Wristband Dashboard.