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 the vanity domains are structured and their uses.

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:

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

• Wristband's Apex Domain: This is Wristband's root domain.
• Region: The geographic region in the Wristband cloud where the application is deployed.
• Your Wristband Tenant Domain Name: This is your Wristband tenant's domain name, i.e., the domain name that was provided when signing up for a Wristband account.
• Application Domain Name: This is the domain name specified when an application 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 Domain Name: This is the domain name specified when a tenant 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 are redirected to and utilize the auth session cookie. For example, the Wristband Authorize Endpoint and Logout Endpoint both require the tenant vanity domain to be used 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 domainName attribute 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 domainName 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.

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 the URL locations. However, when custom domains are defined, the location of these hosted pages will instead utilize the custom domains.

Email Action Links

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

API URLs

Without custom domains, calls made to the Wristband APIs use the default vanity domains. However, when custom domains are enabled, the application and tenant custom domains should 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 enabling custom domains.

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 was used to call the Authorize API, the auth session cookie will be associated with the default tenant vanity domain. On the other hand, if a tenant custom domain was used to call the Authorize API, then the auth session cookie will be associated with the tenant custom domain.

Other Flows

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

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

For these workflows, the authentication session cookie is always associated with the active tenant vanity domain. For example, if no custom domains are enabled, the session cookie will be associated with the default tenant vanity domain. However, if custom domains are enabled, then the session cookie will be associated with the tenant's custom domain.

External Identity Provider URLs

When configuring external identity providers, redirect URLs will be generated so that the external identity provider can redirect back to Wristband after authenticating the user. 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

If an external identity provider was previously configured using a default vanity domain redirect URL, even after enabling custom domains, 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.

Injecting Tenant Domain 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 domain name into the URL. This is primarily useful if your application uses tenant subdomains and you would like to preserve these tenant subdomains for the endpoints that Wristband redirects to.

To have Wristband dynamically insert the tenant domain name into URLs, you need to use the {tenant_domain} token when configuring the URL in Wristband. The {tenant_domain} token 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_domain} token can be used; let's look at an example where a user has configured their OAuth 2 client redirect URI to be:

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

Now imagine a situation where a user successfully logs into a tenant whose domain name is customer01. In this case, when Wristband redirects back to the OAuth 2 client's redirect URI, it will replace the {tenant_domain} token in the URL with the tenant's actual domain name so that the final URL that gets redirected to looks like the following:

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

URLs That Support Tenant Domain Name Injection

Below is a table showing all the places where the {tenant_domain} token is allowed.