Skip to main content

Custom domains

note:

Changing the domain after publishing your service may cause troubles because your application code and integrations might still reference the old domain. To ensure a smooth transition, we recommend setting up your custom domains at the beginning during Production tenant creation.

Your Logto tenant comes with a default free domain {{tenant-id}}.app.logto. However, you can elevate your user experience and brand recognition by using custom domains, like auth.example.com.

Your custom domains are used for several functions:

Multiple custom domains​

Logto now supports configuring multiple custom domains for a single tenant, making your sign-in page accessible from more than one branded domain.

Plan-based limits:

  • Development tenant: Add up to 2 custom domains for free (for testing purposes)
  • Free plan: Add 1 custom domain at no charge
  • Pro plan: Add 1 custom domain included, with the ability to add up to 10 custom domains total through add-ons
  • Enterprise plan: For more than 10 custom domains or custom requirements, please contact us

See the Logto pricing table for detailed information.

With multiple custom domains, you can:

  • Use different domains for various regions, locales, applications, organizations, or top-level domains
  • Build trust by maintaining a consistent brand experience before and after sign-in
  • Provide region-specific or brand-specific authentication experiences by Custom UI

Configure custom domains in Console​

To add a new custom domain in the Logto Console, follow these steps:

  1. Navigate to Console > Settings > Domains.

  2. In "Add a custom domain" section, enter your subdomain (e.g., auth.example.com, auth.us.example.com) and click "add domain".

    Add domain

  3. Copy the CNAME value domains.logto.app in the table, and go to your domain's DNS provider to add record.

    Custom domain processing

  4. Wait for the verification and SSL process.

    1. We will auto-verify your records every 10 seconds until the custom domain is added. Just ensure that the entered domain name or DNS Records are accurate.
    2. Verification typically takes a few minutes but can take up to 24 hours, depending on the DNS provider. Feel free to navigate away during the process.

To add multiple custom domains, simply repeat the above steps for each domain you want to configure.

Troubleshooting​

SSL certificate issues​

If you encounter SSL certificate issues when setting up your custom domain, it may be related to CAA records in your DNS configuration. CAA records specify which Certificate Authorities (CAs) are authorized to issue certificates for your domain. If you're using CAA records, you will need to authorize both "letsencrypt.org" and "pki.goog" for Logto to issue SSL certificates.

To troubleshoot and resolve SSL certificate issues related to CAA records, refer to Cloudflare's documentation on CAA Records.

"The hostname is associated with a held zone" Error​

If you encounter the error message "The hostname is associated with a held zone, please contact the owner to have the hold removed" when adding a custom domain, it means that the domain is already in Cloudflare zone, and it is set to "Zone Hold" status. See this Cloudflare documentation for more information.

To resolve this issue, you'll need to release the zone hold. Follow the above link for instructions on how to release the zone hold in Cloudflare.

Connection timed out (Error code 522) for Cloudflare-hosted domain​

If your domain is hosted on Cloudflare, disable the Cloudflare proxy for the CNAME record.

"Redirect URI does not match" error after setting up custom domain​

If you get a "redirect URI does not match" error after adding your custom domain, you need to update your SDK configuration to use the custom domain as the endpoint.

About "primary domain":

There is no separate "primary domain" setting in Logto. After adding a custom domain, both your custom domain and the default {tenant-id}.logto.app domain remain valid. The domain you configure in your SDK's endpoint parameter determines which domain will be used for authentication flows.

Solution:

Update the endpoint parameter in your SDK initialization to use your custom domain:

const client = new LogtoClient({
  endpoint: 'https://auth.example.com', // Use your custom domain
  appId: 'your-app-id',
  // ... other options
});

Also verify that the redirect URIs registered in Console → Applications match the domain you're using.

Note: Logto automatically provisions and manages SSL certificates for your custom domain. You don't need to configure your own certificates.

Use custom domains​

Once you've configured your settings, both your custom domain name and the default Logto domain name will be available for your tenant. However, certain configurations are required to activate your custom domain name.

note:

In this article, we assume that your custom domain is auth.example.com.

Updating the SDK endpoint for applications​

Alter your initialization code for the Logto SDK by modifying the domain name of the endpoint.

const client = new LogtoClient({
  ...,// other options
  endpoint: 'https://auth.example.com',
});

On the detail page of your application in Console > Applications, scroll to the "Endpoints & Credentials" section. Switch the domain dropdown to view and copy the corresponding endpoints for updating your application settings.

Modifying auth endpoints for other applications​

If you have applications that aren't using the Logto SDK, it's necessary to update their auth endpoints.

You can locate the auth endpoints at the well-known URL:

https://auth.example.com/oidc/.well-known/openid-configuration

Updating social connector redirect URIs​

Social connectors use the OIDC/OAuth protocol. When users sign in through a custom domain, the redirect URI will automatically use that custom domain. You need to update the redirect URI in your social provider's developer console.

Steps:

  1. Navigate to Console > Connectors > Social Connectors and select your connector.
  2. Copy the redirect URI shown in the connector details. Logto lists all available redirect URIs for your configured custom domains.
  3. Add this redirect URI to your social provider's developer console (e.g., Google, GitHub, Facebook).

For multiple custom domains:

  • Add all redirect URIs for each custom domain you've configured. This ensures social login works regardless of which domain users access.
  • The default Logto domain (*.logto.app) remains valid. Include it only if you want to support logins through the default domain as well.
  • For the GitHub connector, use GitHub Apps instead of OAuth apps configured in the GitHub dashboard, as GitHub Apps support multiple redirect URIs. OAuth apps only support a single redirect URI.

Updating OIDC-based enterprise SSO connector redirect URIs​

OIDC-based enterprise connectors follow the same pattern as social connectors.

Steps:

  1. Navigate to Console > Enterprise SSO and select your OIDC connector.
  2. Copy the redirect URIs from the connector details. Logto lists all available redirect URIs for your configured custom domains.
  3. Update the redirect URI in your identity provider (IdP) settings.

For multiple custom domains: Add all corresponding redirect URIs to your IdP to ensure enterprise SSO works across all domains.

Updating SAML-based enterprise SSO connector ACS URLs​

SAML-based enterprise connectors use an Assertion Consumer Service (ACS) URL instead of a redirect URI.

Steps:

  1. Navigate to Console > Enterprise SSO and select your SAML connector.
  2. In the "Configure in the IdP" section, use the domain dropdown to switch between your custom domains.
  3. Copy the ACS URL for the domain you want to support.
  4. Add these ACS URLs to your SAML identity provider configuration.

Important: The domain you select determines where users are redirected after SSO authentication. Configure this based on which domain your application expects to receive the SAML response.

Passkey for MFA​

Passkeys for multi-factor authentication (MFA) are bound to the domain where they were registered. Users must sign in through the same domain to use their Passkeys.

Current limitation: Logto does not yet support cross-domain Passkey verification. If a user registers a Passkey on auth.us.example.com, they must sign in through auth.us.example.com to use that Passkey for authentication. The Passkey registered on one domain cannot be used when signing in through a different custom domain.