Tenant Discovery

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

Application-level Login URL for Wristband-hosted Pages

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 "Your App" with an application domain name of yourapp. The login URLs would look like the following:

Login Type	URL
Application Level	`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:

Login Type	URL
Application Level	`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).

Signup Link on Login Form

If Signup is enabled for your application, there is a Signup Action Link at the bottom of the Login Form on the Wristband-hosted Application-level Login Page.

Signup Action Link

The following is the expected mapping of the Application-level Login Page to Signup Action Link locations:

Login Page	Signup Location
Application-level Login	Application-level Signup

How to Discover Tenants

There are two ways in which a user can find their Tenant-level Login Page when interacting with the Application-level Login Page. The user can either enter their email address for a more consumer-like experience, or they can enter their tenant domain name for a direct path to their Tenant-level Login Page.

Note: You can customize which tenant discovery strategy your application users can perform by configuring the Tenant Discovery Workflow Policy in the Wristband Dashboard. By default, users will first see a form to enter their email address to discover their tenant, and there will also be a link button to let them toggle to using their tenant domain name instead. You have the option to reverse the order so that the tenant domain name strategy appears first instead. Alternatively, you can also configure the workflow policy to only allow for a single discovery strategy, in which case no link button will appear.

Using an Email Address

When you first land on the Application-level Login Page, the user is prompted to enter their email address. When using an email address, the login experience changes depending on how many users in Wristband exist across your application's tenants. If a user with the provided email address can be found only in one tenant for your application, then the user will be automatically redirected to that Tenant-level Login Page.

If a user with the provided email address can be found in two or more tenants for your application, then the user will be sent a Tenant Discovery email. When the user opens that email in their inbox, they will see an action button/link to click. Clicking on that will send them to the Wristband-hosted Tenant Discovery Page. From here, the user will see every tenant they belong to and can choose which Tenant-level Login Page to go to.

Tenant Discovery Page

Using a Tenant Domain

If they want to enter their tenant domain name instead, they can click the link under the form input to change to that experience instead. Providing a tenant domain name will send the user directly to their Tenant-level Login Page.

Enter Email Screen

If they want to go back to entering their email address instead, they can click the link under the form input to change back to that experience.

Enter Tenant Domain Screen