Domains and URLs
Learn how Wristband uses vanity and custom domains for applications and tenants.
Default Vanity Domains
Every application and tenant created in Wristband is automatically assigned a unique vanity domain. These domains serve to identify your resources and generate URLs for API endpoints and hosted pages.
The sections below detail how vanity domains are structured and how they are used.
Figure 1: Diagram showing default application and tenant vanity domains.
Application Vanity Domains
When you create an application, Wristband automatically assigns it a unique vanity domain.
The structural breakdown of a default application vanity domain is as follows:
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:
- Application-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
Similarly, when you create a tenant, Wristband automatically assigns it a unique vanity domain.
The structural breakdown of a default tenant vanity domain is as follows:
Figure 3: Image showing the structure of a default tenant vanity domain.
This follows the exact same structure as an application vanity domain, with one additional component added to the beginning:
- Tenant Name: The unique name assigned to a tenant during creation.
How Tenant Vanity Domains Are Used
Tenant vanity domains are used in the following places:
- Tenant-specific API URLs.
- 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
You can create a custom domain to override the default application or tenant vanity domains. Implementing custom domains provides several key benefits:
- They preserve your application's domain when navigating to Wristband-hosted pages, creating a seamless and trusted user experience.
- They maintain a unified brand identity between your core application and Wristband's hosted pages.
- They provide cleaner, shorter, and more memorable URLs for your users and developers.
Note: Wristband 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 configured, this custom domain applies to all tenants under that application. To maintain uniqueness across tenants, each tenant's name is dynamically prefixed as a subdomain of the application's custom domain.
Application Custom Domain Example
If the application custom domain is auth.yourapp.io and a tenant's name is customer01, the resulting tenant vanity domain will be:
customer01.auth.yourapp.io
Figure 4: Diagram showing application and tenant vanity domains with an application custom domain enabled.
Tenant Custom Domains
Each tenant in Wristband can feature its own fully customized domain, enabling complete white-labeling of the login experience on a per-tenant basis.
Domain Precedence Rules:
- Tenant Overrides Application: If both an application custom domain and a tenant custom domain are defined, the tenant custom domain takes precedence.
- Hybrid Deployments: This configuration allows a hybrid mix: standard tenants use vanity domains derived from the application custom domain, while premium tenants utilize their own fully customized domains.
Figure 5: Diagram showing a combination of applications and tenants with custom domains.
The Affects of Enabling Custom Domains
Enabling custom domains changes how various aspects of the Wristband platform operate.
The sections below highlight the primary changes that occur when custom domains are active:
Hosted Pages
Without custom domains, Wristband's hosted page use your default application and tenant vanity domains. Once custom domains are configured, all hosted page URLs automatically update to utilize your custom domains instead.
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 links included in Wristband emails use your default vanity domains. Once custom domains are active, all email action links automatically update to utilize your custom domains instead.
Figure 7: Image showing how the email action link URL changes when an application custom domain is enabled.
API URLs
Without custom domains, all requests to Wristband APIs must use the default vanity domains. Once custom domains are active, you can utilize your application and tenant custom domains for API calls instead.
Note: Enabling custom domains is completely non-breaking. Your default vanity domains remain fully functional for all Wristband API calls, ensuring existing integrations continue to work without modification.
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 (iss) within access tokens and ID tokens uses the default application vanity domain. Once custom domains are active, the issuer claim updates to match the application custom domain instead.
Figure 9: Image showing how the issuer claim inside access and ID tokens changes when an application custom domain is enabled.
Authentication Session Cookies
Login Flow
When a user logs in, Wristband creates an Auth Session cookie to persist their authenticated state. The domain assigned to this cookie depends entirely on the tenant vanity domain used to call the Wristband Authorize API:
- Using Default Vanity Domains: If a tenant's default vanity domain is used to call the Authorize API, the cookie is scoped to that tenant's default vanity domain.
- Using Custom Domains: If a tenant custom domain is used to call the Authorize API, the cookie is scoped to that tenant custom domain.
Other Flows
Beyond the standard login flow, the following workflows also trigger the creation of an Auth Session cookie:
- Signup
- New User Invite
- Existing User Invite
- Password Reset (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: Enabling custom domains will not break existing authentication setups. If an external identity provider was previously configured with a vanity domain redirect URL, those default vanity domains remain fully functional, ensuring your active integrations continue to work seamlessly without immediate reconfiguration.
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
Wristband frequently needs to redirect users back to your application—such as routing a user to your Callback Endpoint after a successful login. If your application relies on tenant-specific subdomains, Wristband can dynamically inject the tenant's name into the redirect URL to preserve their session context.
To enable this behavior, include the {tenant_name} placeholder when configuring your application URLs in Wristband. The placeholder must adhere to the following rules:
Positioning: It must always be the leftmost domain label in the URL's host.
Usage Limit: It can only be used once within the URL.
Tenant Name Placeholder Example:
The following example illustrates how to implement the {tenant_name} placeholder within an OAuth2 client redirect URI configuration:
https://{tenant_name}.yourapp.io/auth/callbackWhen a user successfully logs into a tenant named customer01, Wristband dynamically replaces the {tenant_name} placeholder with the tenant's actual name.
The final redirection URL will resolve to:
https:/customer01.yourapp.io/auth/callbackURLs That Support Tenant Name Injection
Use the following reference table to view all URL fields fields that allow for the {tenant_name} placeholder:
| 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 |
Updated 9 days ago