Configure custom domains

Configure a custom domain to replace the default *.transmitsecurity.io domain used by Mosaic for identity and authentication flows. This allows your application to communicate with Mosaic through a domain you own.

A custom domain functions similarly to an application subdomain: it determines the token issuer (iss claim), the OIDC discovery endpoint (/.well-known/openid-configuration), and the JWKS location (for more about token signing, see Manage token signing keys).

Once configured, the custom domain is used consistently across all API and SDK calls for the application.

Benefits

Using a custom domain provides several advantages:

• Enhanced privacy: All authentication traffic appears to originate from your domain, not from a third-party service
• Improved user experience: Users see your domain in the browser address bar, maintaining brand consistency
• Reduced blocking: Avoids potential blocking by privacy tools, ad-blockers, or corporate firewalls that may block third-party domains
• Better security posture: Aligns with security policies that restrict third-party domain access
• Personalized tokens: Custom domain affects the token issuer (iss claim) and enables the option for app-specific signing keys
• Seamless integration: Works transparently with all Mosaic features, including token issuance, journeys, and SDKs

Hosting models

Custom domains support two hosting models:

Managed hosting

With managed hosting, Transmit manages the SSL certificate lifecycle. You are responsible for:

• DNS configuration for domain validation
• Adding a Domain Control Validation (DCV) record as instructed by Transmit Security
• Adding a CNAME record pointing your custom hostname to the fallback origin (API Gateway URL) provided by Transmit Security
• Ensuring DNS records are properly configured before requesting activation

Activation time: Managed domains require DNS propagation and validation, which may take some time after configuration.

Custom hosting

With custom hosting, you provide and manage your own SSL certificate and private key. You are responsible for:

• DNS configuration for domain validation
• Adding a CNAME record pointing your custom hostname to the fallback origin (API Gateway URL) provided by Transmit Security
• Providing valid SSL certificate material
• Managing certificate renewals
• Ensuring readiness before requesting activation

Activation time: Custom domains typically activate shortly after certificate upload, once validation is complete.

How to get a custom domain

1. Request custom domain

Custom domains are not enabled by default for Mosaic applications. They must be requested from Transmit Security and may be included in your subscription or available as a paid add-on.

To request a custom domain:

1. Submit a domain request to Transmit Security
   Contact your Transmit representative and specify:

   • Domain name: The domain you want to use (for example, app.acme.com).
     This must be a domain you own and control.
   • Application ID: The Mosaic application that will use the domain
   • Hosting model: Managed hosting or custom hosting
   • DNS access: Ability to configure DNS records for domain validation If you choose custom hosting, you must also provide:
   • SSL certificate for the domain
   • Private key corresponding to the certificate
   • Full certificate chain, if applicable

2. Approval and provisioning
   Transmit Security reviews the request and provisions the domain for the appropriate environment and region based on your tenant configuration.

3. DNS validation
   Configure the required DNS records as instructed by Transmit Security:

   • For managed hosting: Add a Domain Control Validation (DCV) record and a CNAME record pointing to the fallback origin (API Gateway URL) provided by Transmit Security
   • For custom hosting: Add a CNAME record pointing to the fallback origin (API Gateway URL) provided by Transmit Security

   Once validation completes, the custom domain is activated. Your Transmit representative will complete the final configuration to link the custom domain to your application. After configuration, the custom domain will be used for authentication flows, token issuance, and API calls.

   Custom domains are configured per application. Different applications within the same tenant can use different custom domains.

2. Configure network and security

When switching to a custom domain, update your network and security configuration accordingly. If your firewall previously allowed Transmit domains:

• Remove the need to allow *.transmitsecurity.io
• Allow your custom domain instead (for example, app.acme.com)

See Enable API communication for details.

3. Update your Content Security Policy (CSP)

If you use a Content Security Policy, update the connect-src directive to include your custom domain:

connect-src: <existing-content> https://app.acme.com

If you are exclusively using a custom domain, you can remove Transmit domains from your CSP configuration.

For more information, see Enable API communication.

SDKs and APIs

After configuring a custom domain, you must use it when initializing SDKs and making API calls.

SDK usage: All SDKs support custom domains by replacing the default Transmit domain with your custom domain in the existing configuration parameters. The parameter name varies by SDK:

• Web SDK: serverPath for each module included in your project (for example, in ido, drs, idv, or webauthn objects). Replace https://api.transmitsecurity.io with your custom domain in each serverPath, keeping all path postfixes (for example, https://api.transmitsecurity.io/risk-collect/ becomes https://app.acme.com/risk-collect/)
• iOS Orchestration SDK: baseUrl (in plist) or serverPath (in initialization parameters)
• iOS Authentication SDK: baseUrl and domain parameters in TSAuthentication.shared.initialize()
• Android SDK: transmit_security_base_url (in strings.xml) or baseUrl (in initialization parameters)
• React Native: baseUrl (iOS plist) or transmit_security_base_url (Android strings.xml)

These parameters are used together with clientId for SDK initialization. Installation steps remain the same regardless of whether you use a custom domain.

API usage: Use your custom domain as the base URL for all API calls instead of the default Transmit domain (for example, https://api.transmitsecurity.io).

For detailed information on configuring custom domains in SDKs and APIs, see the SDK References and the API Reference introduction.

Monitoring and troubleshooting

Monitor your custom domain configuration through:

• DNS validation status
• SSL certificate status (for custom hosting)

If you encounter issues, contact Transmit Security support.