# Custom Domain

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

```text
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:

```text
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[​](#configuration "Direct link to Configuration")

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

```text
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[​](#request-routing "Direct link to Request Routing")

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

| Path                   | Custom domain | Notes                                 |
| ---------------------- | ------------- | ------------------------------------- |
| `/client.js`           | Served        | SDK loader entry point                |
| `/assets/*`            | Served        | Compiled SDK bundles                  |
| `/api/*`               | Served        | All SDK API endpoints                 |
| `/third-party/*`       | Served        | Social login popups opened by the SDK |
| `/checkout/processing` | Served        | Post-checkout processing page         |
| `/.well-known/*`       | Served        | OIDC discovery and JWKS endpoints     |
| All other paths        | Redirected    | Permanent (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[​](#cors "Direct link to 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[​](#how-the-sdk-uses-the-custom-domain "Direct link to 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.

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

```

## Local Development[​](#local-development "Direct link to 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.

## Related[​](#related "Direct link to Related")

* [Script Tag](/developer/guides/script-tag.md) — Embedding the SDK on your site
* [Stripe Webhook Setup](/developer/platform/stripe-webhooks.md) — Configuring the Stripe webhook endpoint