# Tenant domains

## Canonical domain

New tenants get `https://YOUR-TENANT.YOUR-REGION.auth0.com`, e.g. `YOUR-TENANT.us.auth0.com`. The region is part of the domain. The OIDC issuer is this URL with a trailing slash: `https://YOUR-TENANT.YOUR-REGION.auth0.com/`. Token `iss` claims and the `/.well-known/openid-configuration` discovery document use it.

## Rules

- Use the full canonical domain everywhere: issuerBaseURL, JWKS URL, Management API base.
- Never guess the region. Copy it from Dashboard > Settings, or from Tenant Settings in the Management API.
- The tenant name alone (`YOUR-TENANT`) is not a domain; requests to it fail DNS or route to the wrong region.

## Custom domains

A custom domain (`login.YOUR-DOMAIN`) is a mask over the canonical domain: users see your brand in the URL bar, and cookies become first-party (fixes Safari ITP silent-auth issues). Setup: add the domain in Dashboard > Branding > Custom Domains, choose Auth0-managed certificates (they handle issuance and renewal) or self-managed, add the CNAME record at your DNS, complete verification.

Caveats agents hit:

- Feature table: not every Auth0 feature works through the custom domain; check the docs table for your feature (notably some Management API and edge behaviors still use the canonical domain).
- Token `iss`: by default the issuer stays the canonical domain even when authenticating through the custom domain. API validators must accept the canonical issuer, or configure the issuer accordingly.
- After verifying, update the SDK domain values and the callback/logout URL registrations to the custom domain; mixed domains cause cookie and issuer mismatches.

## Checklist

- Canonical domain copied from the dashboard, not guessed.
- If using a custom domain, SDKs and URL allowlists point at it consistently.