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.

Hosting the platform

This page covers configuring a custom domain when you host Allegro yourself. If you are embedding the SDK on your site and just need to understand how a custom domain affects your integration, see Custom Domain under Administration.

Domain Inventory​

Domains are no longer typed directly into a tenant or property field. Instead, each tenant has an inventory of domains, managed from the Allegro Admin: open a tenant and go to its Domains tab.

Adding a domain there provisions it at your configured hosting provider — DNS records are created for it and a certificate is requested — but assigns it to nothing. A newly added domain does not yet serve any traffic. This separates "this domain is ready to use" from "this domain is in use," so a domain can be fully provisioned and verified ahead of a cutover with no window where it serves without HTTPS.

Assigning a Domain​

A domain in the inventory routes only once it is assigned, in one of two ways:

  • As the tenant's own domain. From the Domains tab, choose Set as tenant domain on a domain's row. This is now the only way to set a tenant's domain — it must come from the tenant's own inventory rather than being typed in directly.
  • To a property. From that property's own settings page, its Custom Domain field is a select populated from the tenant's inventory, offering only domains not already assigned elsewhere in the tenant.

An unassigned domain in the inventory does not route: a request against it returns a 404 until it is assigned as the tenant's domain or to a property.

A property's domain must stay in the inventory

If a property's assigned domain is ever removed from the tenant's inventory — for example, deleted from the Domains tab — that property's settings page can no longer be saved at all, not even for unrelated fields, until the domain is re-added to the inventory or the property's Custom Domain is cleared. This is enforced server-side, so it cannot be bypassed from a hand-crafted request either.

DNS Records​

Provisioning a domain from the Domains tab produces at least two DNS records, shown in that domain's row (expand it to see them). Create both at your DNS provider:

  1. An origin record (typically an A record) that points the domain's traffic at your hosting provider.
  2. An SSL validation record (a CNAME at _acme-challenge.<domain>, under Let's Encrypt's DNS-01 verification) that the certificate authority uses to prove you control the domain.

Some hosting providers also require a third ownership record before the origin record takes effect. Copy the exact values from the Domains tab rather than guessing — they are specific to your provider and this provisioning.

The SSL validation CNAME is permanent

Unlike a one-time ownership check, the SSL validation CNAME is re-checked on every certificate renewal. Removing it after the domain goes live will not break the domain immediately, but the next renewal will fail and the domain will eventually serve without a valid certificate. Leave it in place for as long as the domain is in use.

Verification​

After you create the DNS records, Allegro verifies the domain in the background — you do not have to trigger anything. Each domain's row on the Domains tab shows its progress across the checks that apply to your provider:

StatusMeaning
PendingThe check has not passed yet — usually waiting for DNS to propagate.
VerifiedThe check passed.
FailedThe check could not be completed; the row shows the error returned.
Not requiredThe check does not apply to this provider.

Allegro re-checks a pending domain often at first and less frequently as time passes. A domain that stays unverified for more than a week is marked stalled — Allegro stops re-checking it, but nothing is lost: fix the DNS records and re-check the domain from its row to resume. The domain is considered ready once every applicable check has passed.

Hosting Provider Configuration​

Provisioning requires a hosting provider to be configured:

ALLEGRO_HOSTING_PROVIDER=laravel-forge

Set it to a registered provider name (laravel-forge or laravel-cloud), then configure that provider package's own environment variables — see packages/allegro-laravel-forge or packages/allegro-laravel-cloud. Until ALLEGRO_HOSTING_PROVIDER and the provider's own variables are all set, the Domains tab renders a disabled state and existing inventory rows are shown but cannot be added to, verified, or assigned.

Existing domains still appear

A domain that was already set as a tenant's or property's domain before this inventory model existed is backfilled into the tenant's inventory automatically, so it appears on the Domains tab without any manual step. If your deployment has not yet configured a hosting provider, those backfilled domains still display, just without live provisioning until the provider is configured.

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.

The same allowed-origin list also governs return URLs. The returnUrl passed to magic link requests and the return URL passed to checkout must resolve to one of these origins, otherwise the request is rejected. This prevents sign-in and purchase tokens from being redirected to domains the tenant does not control.

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.