Site Home
API Reference
LoginTry for Free

URL Domains

Learn about the different domains used in Wristband API URLs.

Application vs. Tenant Vanity Domains

When calling Wristband APIs, the URL must include either an application vanity domain or a tenant vanity domain.

📘

Learn More

If you'd like more information about application and tenant vanity domains, see the Domains and URLs documentation.

For most APIs, Wristband requires an application vanity domain. However, for the following cases, a tenant vanity domain is required:

  1. APIs that require redirects
    • Ensures the auth session cookie is sent correctly, since auth session cookies are bound to tenant vanity domains.
    • Ensures that custom tenant domains, if enabled, appear in the browser history, preserving the tenant’s white-labeled branding.
  2. APIs that use the vanity domain as a tenant identifier
    • In these cases, the tenant vanity domain determines which tenant the request is scoped to.

Identifying APIs That Require a Tenant Vanity Domain

In the API reference, any API that requires a tenant vanity domain includes a blockquote with the header:

🏢

Tenant Vanity Domain Required

If an API does not explicitly state that a tenant vanity domain is required, then an application vanity domain should be used instead.

Example

To help illustrate how application and tenant vanity domains should be used when calling Wristband APIs, let's take an example where you have an application and tenant with the following vanity domains:

  • Application Vanity Domain: yourapp-yourorg.us.wristband.dev
  • Tenant Vanity Domain: org1-yourapp-yourorg.us.wristband.dev

In this case, to call the Get User API, which requires an application vanity domain, you would construct your URL as follows: 

https://yourapp-yourorg.us.wristband.dev/api/v1/users/{userId}

However, if you wanted to call the Authorize API, which requires a tenant vanity domain, the URL would be constructed as: 

https://org1-yourapp-yourorg.us.wristband.dev/api/v1/oauth2/authorize

Locating Vanity Domains From the Dashboard

Application and tenant vanity domain values can be found in the Wristband dashboard.

Locating Application Vanity Domains

From the Wristband dashboard home page, select the application whose vanity domain you'd like to view.

Select application

You should now land on the "Application Settings" page. From this page, you can copy the application vanity domain from the "Default Vanity Domain" field.

Copy default vanity domain

If you have an active application custom domain, you can use this value as the application vanity domain in the API URLs as well. The application custom domain, if defined, can be copied from the "Active Custom Domain" field.

Copy active custom domain

Locating Tenant Vanity Domains

From the Wristband dashboard home page, select the application that the tenant belongs to.

Select application

Next, select "Tenants" from the left navigation menu and then select the tenant from the table whose vanity domain you'd like to view.

Select tenant

You should now land on the "Tenant Settings" page. From this page, you can copy the tenant vanity domain from the "Default Vanity Domain" field.

Copy tenant vanity domain

If you have an active tenant custom domain, you can use this value as the tenant vanity domain in the API URLs as well. The tenant custom domain, if defined, can be copied from the "Active Custom Domain" field.

Copy tenant custom domain