Skip to main content
Version: Early Access

Vanity Subdomains in the Platform

A vanity Subdomain is a distinct, user-friendly, and URL-friendly identifier assigned to each account or tenant within the Digital.ai Platform. It is designed to simplify tenant identification and enhance usability by providing a clean and meaningful representation of the tenant in URLs.

Vanity Subdomains are frequently used in multi-tenant Saas applications, as they provide unique identifiers for different customers accessing a web application, such as staging, EU, and US.

warning

Changing the vanity subdomain offers flexibility but comes with important considerations. Always evaluate the potential impacts on IDP configurations, user bookmarks, and invitations before making changes.

When a customer's tenant is automatically created in the Digital.ai Platform, the tenant name undergoes a standardization process. This ensures the name is formatted appropriately to create the default subdomain. The standardization process includes the following steps:

  • Converting the name to lowercase.
  • Removing any spaces and special characters.
  • Producing a clean, URL-safe subdomain name.

For example, if a customer like The Widget Emporium wants their Platform to be represented by the acronym "widget", the user-defined subdomain might look like widget.us.digital.ai.

Customers have the flexibility to edit this vanity subdomain in the Account Settings page to better suit their branding needs. However, changing the vanity subdomain can have significant implications that users must be aware of.

Key Uses of Vanity Subdomains

  1. Account-Specific URLs
    Vanity Subdomains are embedded in URLs to uniquely identify a Platform account.
  • The Digital.ai Platform UI, for instance, incorporates the vanity domain to route users directly to their Platform interface.
  1. Authentication and Identity Service Integration
    Vanity domains are integral to the identity service, where they are used to:
  • Map incoming authentication requests to the correct tenant.
  • Determine customer-specific authentication rules and identity provider (IDP) configurations.
  • Ensure secure and seamless handling of user authentication.

Edit Your Vanity Subdomain

A vanity subdomain allows you to customize the URL used to access your account. Follow these steps to edit your vanity subdomain.

  1. Log in to your account. Go to the Accounts section under Settings

Vanity Domain

  1. Locate the Vanity Domain field. Click Edit.

  2. Enter the new vanity subdomain in the provided field. Click Update Vanity Domain to save your changes.

Vanity Sub Domain

Side Effects of Editing Vanity Subdomains​

Impact on IdP Configuration​

If an Identity Provider (IdP) configuration is already configured, modifying the vanity subdomain will require the following actions:

  • The IDP configuration will need to be updated or recreated to reflect the new URLs.
  • For example, IDPs like Entra ID rely on the correct URLs for proper authentication. Any mismatch in the URL can result in authentication failures.
note

Ensure that your IDP configuration is updated immediately after changing the vanity subdomain to avoid service disruptions.

Broken Bookmarks​

Editing the vanity subdomain will result in any bookmarks created with the previous URL becoming invalid. Users who rely on these bookmarks will need to:

  • Locate the new URL.
  • Update their bookmarks manually.
note

This may lead to confusion or difficulty accessing the Platform until the bookmarks are corrected.

Broken User Invitations​

Any user invitations sent before the vanity subdomain change will no longer be functional. This is because:

  • The invitation URLs embed the vanity subdomain.
  • When the subdomain changes, the links within the invitations will point to a non-existent or incorrect location.
note

After updating the vanity subdomain, notify your users of the new URL and the need to update their bookmarks.

Last updated on