Domains and URLs

Default Vanity Domains

All applications and tenants created in Wristband are assigned a default vanity domain. These vanity domains uniquely identify an application or tenant within Wristband and are used to generate URLs for API calls and hosted pages. In the sections below, we'll dive into how vanity domains are structured and how they're used.

Application Vanity Domains

When you create an application in Wristband, a unique vanity domain is assigned to it. Here is a breakdown of the structure of a default application vanity domain:

App Vanity Domain Structure — Figure 2. Image showing the structure of a default application vanity domain.

Working from right to left on each of the domain parts:

Wristband's Apex Domain: This is Wristband's apex domain.
Region: The geographic region in the Wristband cloud where the application is deployed.
Your Wristband Tenant Name: This is your Wristband tenant's name.
Application Name: The name given to an application when it is created.

How Application Vanity Domains Are Used

Application vanity domains are used in the following places:

Non-tenant-specific API URLs.
Application-level hosted page URLs.
OAuth 2 Redirect URIs for identity providers created at the application level.
Issuer claims in access and ID tokens.

Tenant Vanity Domains

Like applications, when you create a tenant in Wristband, a unique vanity domain is assigned to it. Here is a breakdown of the structure of a default tenant vanity domain:

The structure is the same as a default application vanity domain, except there is one additional part at the beginning of the domain:

Tenant Name: The name given to a tenant when it is created.

How Tenant Vanity Domains Are Used

Tenant vanity domains are used in the following places:

Tenant-specific API URLs. These are APIs that typically rely on tenant-level cookies. For example, the Wristband Authorize Endpoint and Logout Endpoint both use the tenant-level Auth Session cookie, so they require the tenant vanity domain as the URL host.
Tenant-level hosted page URLs.
As the domain of Wristband Auth Session cookies.
OAuth 2 Redirect URIs for identity providers created at the tenant level.
SAML ACS URLs and SP entity IDs for identity providers created at the tenant level.

Custom Domains

To override the default application or tenant vanity domains, you can create a custom domain. Custom domains offer several benefits:

They preserve your application's domain when navigating to Wristband's hosted pages, increasing user trust
They maintain consistent branding between your application and Wristband's hosted pages.
They provide cleaner, more memorable URLs.

ℹ️
Our custom domains are powered by SaaS Custom Domains

Application Custom Domains

An application custom domain allows you to replace the default application vanity domain with a domain of your choice.

When an application custom domain is configured, all tenants under that application will use it. To ensure each tenant's vanity domain remains unique, the tenant's name is used as a subdomain of the application's custom domain.

Example

If the application custom domain is auth.yourapp.io and a tenant's name is customer01, that tenant's vanity domain will be:

customer01.auth.yourapp.io

Tenant Custom Domains

Each tenant in Wristband can have its own fully customized domain, enabling complete white-labeling of the login experience on a per-tenant basis.

If both an application custom domain and a tenant custom domain are defined, the tenant custom domain takes precedence. This allows you to have a mix of tenants using vanity domains derived from the application custom domain and tenants with their own fully customized domains.

Tenant Custom Domains — Figure 5. Diagram showing a combination of applications and tenants with custom domains.

The Affects of Enabling Custom Domains

Enabling custom domains affects various aspects of the Wristband platform. In the following sections, we will highlight the main changes that occur when custom domains are enabled.

Hosted Pages

Without custom domains, Wristband's hosted pages will use the default application and tenant vanity domains for their URLs. However, when custom domains are defined, the location of these hosted pages will instead utilize the custom domains.

Tenant Login with Custom Domains — Figure 6. Image showing how the tenant login page URL changes when an application custom domain is enabled.

Email Action Links

Without custom domains, the action link URLs in Wristband emails will use default vanity domains. However, after enabling custom domains, all email action links will use custom domains instead.

API URLs

Without custom domains, calls made to the Wristband APIs use the default vanity domains. However, when custom domains are enabled, application and tenant custom domains can be used instead.

ℹ️
Note
Even with custom domains enabled, the default vanity domains can still be used to call Wristband APIs. This ensures that existing Wristband API calls won't break when custom domains are enabled.

API Calls with Custom Domains — Figure 8. Image showing how a Wristband API URL changes when an application custom domain is enabled.

Token Claims

Without custom domains, the issuer claim within access tokens and ID tokens will use the default application vanity domain. However, when application custom domains are enabled, the issuer claim will use the application custom domain instead.

Authentication Session Cookies

Login Flow

When a user logs in, Wristband creates an Auth Session cookie to persist the user's authenticated state. The domain that the Auth Session cookie is associated with depends on the domain used to call the Wristband Authorize API. For example, if the default tenant vanity domain is used to call the Authorize API, the Auth Session cookie will be associated with that domain. On the other hand, if a tenant's custom domain is used to call the Authorize API, the Auth Session cookie will be associated with that domain.

Other Flows

In addition to the login flow, the following workflows can also trigger the creation of an Auth Session cookie:

Signup
New User Invite
Existing User Invite
Forgot Password (if the "Immediate Login" workflow policy is enabled).

For these workflows, the Auth Session cookie will be associated with the tenant's custom domain, if custom domains are enabled; otherwise, it will be associated with the tenant's default vanity domain.

External Identity Provider URLs

When configuring external identity providers, redirect URLs will be generated so the external identity provider can redirect the user back to Wristband after authentication. If no custom domains are enabled, the redirect URLs will use the default vanity domains. However, if custom domains are enabled, the redirect URLs will be generated using the custom domains.

ℹ️
Note
Even after enabling custom domains, if an external identity provider was previously configured with a default vanity domain redirect URL, the default vanity domains will continue to work. This means that you don't have to worry about previous identity provider integrations breaking if custom domains are enabled.

Redirect URLs with Custom Domains — Figure 10. Image showing how an application-level Google Social IdP redirect URI changes when an application custom domain is enabled.

Injecting Tenant Names Into Redirect URLs

There are certain scenarios where Wristband needs to redirect back to your application. For example, after a user successfully logs in, Wristband will redirect to your application's Callback Endpoint. When performing these redirects to your application, Wristband can dynamically inject the tenant's name into the URL. This is primarily useful if your application uses tenant subdomains and you would like to preserve them for the endpoints Wristband redirects to.

To have Wristband dynamically insert the tenant name into URLs, you need to use the {tenant_name} placeholder when configuring the URL in Wristband. The {tenant_name} placeholder must:

Always be the leftmost domain label in the URL's host.
Only be used once in the URL.

Example

To illustrate how the {tenant_name} placeholder can be used, let's look at an example where a user has configured their OAuth2 client redirect URI to be:

https://{tenant_name}.yourapp.io/auth/callback

Now, imagine a situation in which a user successfully logs in to a tenant named customer01. In this case, when Wristband redirects back to the OAuth2 client's redirect URI, it will replace the {tenant_name} token in the URL with the tenant's actual name so that the final URL that gets redirected to looks like the following:

https:/customer01.yourapp.io/auth/callback

URLs That Support Tenant Name Injection

Below is a table showing all the places where the {tenant_name} placeholder is allowed.

Wristband Entity	Fields
Application	`loginUrl`, `logoutUrls`, `customTenantSignupPageUrl`, `customTenantLoginPageUrl`,`customExternalIdpTenantSignupPageUrl`, `customExternalIdpLoginPageUrl`, `customExternalIdpInvitePageUrl`, `customExternalIdpChangeEmailPageUrl`, `customTenantErrorPageUrl`
OAuth2 Client	`loginUrl`, `redirectUris`
Email Policy	`actionLinkUrl`
Workflow Policy	`customRedirectUrl`, `customInvitationLinkUrl`, `customPasswordResetLinkUrl`