Skip to main content

Custom Domain

By default, the Allegro SDK is loaded from a tenant subdomain:

https://acme.allegrocdp.com/client.js

A custom domain lets you serve the SDK and its API endpoints from a domain you control — for example:

https://cdn.acme.com/client.js

When a member's browser loads client.js from your domain, the SDK uses that same origin for all subsequent API requests. The custom domain and the subdomain are kept in sync: the subdomain always stays active and continues to serve your admin dashboard and all other platform traffic.

Configuration​

Set the domain field on the tenant to your custom domain (without scheme or trailing slash):

cdn.acme.com

DNS for that domain must point to your Allegro instance. No path prefix is required — Allegro handles routing based on the hostname.

HTTPS only

Custom domains must be served over HTTPS. Allegro generates redirect and CORS URLs using https:// unconditionally.

Request Routing​

Not all paths are available on the custom domain. Allegro routes requests as follows:

PathCustom domainNotes
/client.jsServedSDK loader entry point
/assets/*ServedCompiled SDK bundles
/api/*ServedAll SDK API endpoints
/third-party/*ServedSocial login popups opened by the SDK
/checkout/processingServedPost-checkout processing page
/.well-known/*ServedOIDC discovery and JWKS endpoints
All other pathsRedirectedPermanent (301) redirect to subdomain

Any request on the custom domain that does not match one of the served paths is permanently redirected to the equivalent path on the tenant's subdomain. This keeps the admin dashboard and authentication flows on the canonical subdomain regardless of which domain the SDK is loaded from.

Subdomain stays active

The subdomain (acme.allegrocdp.com) is never disabled. All operator traffic — the dashboard, login, settings — continues to work there. The custom domain is an additional entry point for audience-facing requests only.

CORS​

When a custom domain is configured, Allegro automatically includes it in the list of allowed CORS origins alongside the subdomain. No additional configuration is needed.

If your deployment requires additional allowed origins (for example, a preview environment), add them to the cors_allowed_origins tenant setting.

How the SDK Uses the Custom Domain​

The SDK determines its API base URL from the src attribute of the <script> tag that loads client.js. If you load the script from your custom domain, all API calls the SDK makes — authentication, event tracking, interactions, checkout — go to the custom domain automatically. No additional configuration in the SDK embed code is required.

<!-- All SDK API requests go to cdn.acme.com -->
<script src="https://cdn.acme.com/client.js" data-tenant="acme"></script>

Local Development​

By default, Allegro permanently redirects any request on the custom domain that does not match an allowed path to the equivalent path on the tenant's subdomain. This can interfere with local or staging setups where you need to access the admin dashboard through a custom domain.

Set ALLEGRO_DISABLED_REDIRECT_CANONICAL=true in your environment to disable this redirect entirely. When set, requests to non-SDK paths on the custom domain are served directly rather than being redirected to the subdomain. Allegro also automatically scopes the session cookie to the custom domain for that tenant so authentication works correctly.

warning

Do not set ALLEGRO_DISABLED_REDIRECT_CANONICAL=true in production. It disables a security boundary that prevents audience-facing custom-domain traffic from reaching the operator dashboard.