Multiple Custom Domains (MCD) Early Access

Multiple Custom Domains (MCD) support in a single tenant is currently available in Early Access (EA). This capability is available only for Enterprise customers. If you are interested in using this feature, please reach out to your Sales exec/Technical Account Manager or open a support ticket through the Auth0 Support Center.

To learn more about Auth0's product release cycle, review Product Release Stages.

Within Auth0, a custom domain allows you to unify the login experience with your own brand and products. Multiple custom domains EA capability enables you to configure up to 1000 custom domains within a single Auth0 tenant. Please see the prerequisites below, including the applicable limits and conditions at General Availability (GA).

Prerequisites

Before getting started with MCD, review the requirements below:

Your tenant is on an Enterprise plan (Public Cloud or Private Cloud deployments). For more information, see Manage Subscriptions.
Your Enterprise plan will provide a base entitlement of up to 20 custom domains per tenant in the MCD General Availability (GA) release.
EA allows up to 1,000 custom domains per tenant for experimentation and validation. Once MCD GA launches, the base entitlement of up to 20 custom domains will apply. Any domains beyond the base entitlement will require an additional add-on SKU.
You must be able to prove ownership of the configured custom domains.

Configure Multiple Custom Domains

Auth0 will enable the MCD feature on tenants requested by EA participants. You can then add MCD to a tenant with the Management API or in the Auth0 Dashboard.

To create a custom domain in the Auth0 Dashboard:

Navigate to Auth0 Dashboard > Branding > Custom Domains.
Select +Add custom domain.
In the configuration form, provide the following information:
- Domain: A fully-qualified domain name that you own. For example: my.custom-domain.com.
- Certificate type: Choose Auth0-managed certificates or Self-managed certificates.
- Metadata (Key/Value): Add optional metadata like region, client_name, or client_id, to help organize and filter your domains.
Once you have configured the custom domain details, select Save.

Your newly added domain name will show as pending until verification is complete.

To create a custom domain with the Management API, you need a machine-to-machine (M2M) application that is authorized to use the Management API. For more information, review. For more information, review Management API Access Tokens.

Navigate to Dashboard > Applications > Applications and select Create Application.
Enter a descriptive name for your application and choose Machine to Machine Applications. Then, select Create.
Switch to the APIs view and then enable toggle for the Auth0 Management API.
Expand the row to configure API’s permissions. For MCD, you must select the following:
- read:custom_domains
- create:custom_domains
- update:custom_domains
- delete:custom_domains
Select Update.
Navigate to the Settings tab to gather your Client ID, Client Secret, and Domain.
Review Get Management API Access Tokens to retrieve and store your access token.

Create a Custom Domain

You can create a new custom domain by sending a POST request to the /api/v2/custom-domains endpoint. See the example below to create a new custom domain using the Management API explorer, using the credentials retrieved above:

cURL
C#
Go
Java
Node.JS
Obj-C
...

curl --request POST \
  --url 'https://{yourDomain}/api/v2/custom-domains' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
  --header 'content-type: application/json' \
  --data '{ 
 "domain": "your.example-custom-domain.com", 
 "type": "auth0_managed_certs", 
 "tls_policy": "recommended", 
 "custom_client_ip_header": "true-client-ip", 
 "domain_metadata": {
    "environment": "development"} 
}'

Was this helpful?

var client = new RestClient("https://{yourDomain}/api/v2/custom-domains");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
request.AddHeader("content-type", "application/json");
request.AddHeader("accept", "application/json");
request.AddParameter("application/json", "{ \n \"domain\": \"your.example-custom-domain.com\", \n \"type\": \"auth0_managed_certs\", \n \"tls_policy\": \"recommended\", \n \"custom_client_ip_header\": \"true-client-ip\", \n \"domain_metadata\": {\n    \"environment\": \"development\"} \n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Was this helpful?

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://{yourDomain}/api/v2/custom-domains"

	payload := strings.NewReader("{ \n \"domain\": \"your.example-custom-domain.com\", \n \"type\": \"auth0_managed_certs\", \n \"tls_policy\": \"recommended\", \n \"custom_client_ip_header\": \"true-client-ip\", \n \"domain_metadata\": {\n    \"environment\": \"development\"} \n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")
	req.Header.Add("content-type", "application/json")
	req.Header.Add("accept", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Was this helpful?

HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/custom-domains")
  .header("authorization", "Bearer {yourMgmtApiAccessToken}")
  .header("content-type", "application/json")
  .header("accept", "application/json")
  .body("{ \n \"domain\": \"your.example-custom-domain.com\", \n \"type\": \"auth0_managed_certs\", \n \"tls_policy\": \"recommended\", \n \"custom_client_ip_header\": \"true-client-ip\", \n \"domain_metadata\": {\n    \"environment\": \"development\"} \n}")
  .asString();

Was this helpful?

var axios = require("axios").default;

var options = {
  method: 'POST',
  url: 'https://{yourDomain}/api/v2/custom-domains',
  headers: {
    authorization: 'Bearer {yourMgmtApiAccessToken}',
    'content-type': 'application/json',
    accept: 'application/json'
  },
  data: {
    domain: 'your.example-custom-domain.com',
    type: 'auth0_managed_certs',
    tls_policy: 'recommended',
    custom_client_ip_header: 'true-client-ip',
    domain_metadata: {environment: 'development'}
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Was this helpful?

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}",
                           @"content-type": @"application/json",
                           @"accept": @"application/json" };
NSDictionary *parameters = @{ @"domain": @"your.example-custom-domain.com",
                              @"type": @"auth0_managed_certs",
                              @"tls_policy": @"recommended",
                              @"custom_client_ip_header": @"true-client-ip",
                              @"domain_metadata": @{ @"environment": @"development" } };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/custom-domains"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];

Was this helpful?

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{yourDomain}/api/v2/custom-domains",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{ \n \"domain\": \"your.example-custom-domain.com\", \n \"type\": \"auth0_managed_certs\", \n \"tls_policy\": \"recommended\", \n \"custom_client_ip_header\": \"true-client-ip\", \n \"domain_metadata\": {\n    \"environment\": \"development\"} \n}",
  CURLOPT_HTTPHEADER => [
    "accept: application/json",
    "authorization: Bearer {yourMgmtApiAccessToken}",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Was this helpful?

import http.client

conn = http.client.HTTPSConnection("")

payload = "{ \n \"domain\": \"your.example-custom-domain.com\", \n \"type\": \"auth0_managed_certs\", \n \"tls_policy\": \"recommended\", \n \"custom_client_ip_header\": \"true-client-ip\", \n \"domain_metadata\": {\n    \"environment\": \"development\"} \n}"

headers = {
    'authorization': "Bearer {yourMgmtApiAccessToken}",
    'content-type': "application/json",
    'accept': "application/json"
    }

conn.request("POST", "/{yourDomain}/api/v2/custom-domains", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Was this helpful?

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://{yourDomain}/api/v2/custom-domains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request.body = "{ \n \"domain\": \"your.example-custom-domain.com\", \n \"type\": \"auth0_managed_certs\", \n \"tls_policy\": \"recommended\", \n \"custom_client_ip_header\": \"true-client-ip\", \n \"domain_metadata\": {\n    \"environment\": \"development\"} \n}"

response = http.request(request)
puts response.read_body

Was this helpful?

import Foundation

let headers = [
  "authorization": "Bearer {yourMgmtApiAccessToken}",
  "content-type": "application/json",
  "accept": "application/json"
]
let parameters = [
  "domain": "your.example-custom-domain.com",
  "type": "auth0_managed_certs",
  "tls_policy": "recommended",
  "custom_client_ip_header": "true-client-ip",
  "domain_metadata": ["environment": "development"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/custom-domains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Was this helpful?

If successful, you should see the following returned with the details of your new custom domain, including it's verification status. The status is initially returned as pending.

{
    "custom_domain_id": "cd_abc123def456",
    "domain": "your.example-custom-domain.com",
    "primary": false,
    "status": "pending",
    "type": "auth0_managed_certs",
    "verification": {
        "methods": [
            {
                "name": "CNAME",
                "record": "yourtenant.auth0.com",
                "domain": "your.example-custom-domain.com"
            }
        ]
    },
    "tls_policy": "recommended",
    "domain_metadata": {
        "environment": "development"
    }
}

Was this helpful?

MCD features

MCD offers many key features and functionalities to more effectively manage your Auth0 implementation and improve user experience. You are responsible for owning and registering your desired custom domains with a domain name registrar.

The Auth0 Management API provides comprehensive support for Create, Read, Update, Delete, and Verify operations for these custom domains, offering full programmatic control over their lifecycle.

MCD EA supports the following Auth0 SDKs: Node.js and Go.

Domain verification

The method for verifying domain name ownership depends on your chosen management type:

Domain Type	Verification Method	Details
Auth0-Managed	CNAME DNS record	Configure this record to confirm domain ownership and activate your domain.
Self-Managed	TXT DNS record	Specific TXT record details are provided in the Create API response.

After your custom domain has been verified by Auth0, you can use it immediately to configure Auth0 features for your users. For more information, read Configure Features to Use Custom Domains.

Metadata for enhanced management

You can provision up to 10 metadata fields per custom domain for easier organization and future customization. In upcoming releases, these metadata fields will enable advanced customization of email templates, Universal Login, and authentication logic.

Customize email templates

Leverage your custom domain information to personalize and brand your email templates, ensuring a consistent user experience. To facilitate this, MCD provides the custom_domain.domain variable for use in Liquid Syntax.

For example, you could set the From Address of your email template to support@{{ custom_domain.domain }} , which would render as support@my.custom-domain.com. This variable is available through Liquid Syntax in the From Address, Subject, and Message fields. To learn more, read Customize Email Templates.

Customize email handling using the Management API

If you configured Multiple Custom Domains and enabled Use Custom Domains in Emails, the auth0-custom-domain HTTP header is available when using the Auth0 Management API. The header is passed as the value for the domain object in email templates.

The auth0-custom-domain HTTP header is required if multiple custom domains are configured and in the ready state. If you are moving from a single custom domain to MCD, you must update your existing Management API email requests to include the auth0-custom-domain HTTP header .

The following Management API endpoints accept the auth0-custom-domain HTTP header:

For example: To create a password change ticket using Auth0 SDK for Node.js.

const { ManagementClient } = require('auth0');

const auth0 = new ManagementClient({
    domain: '<YOUR_AUTH0_DOMAIN>',
    clientId: '<YOUR_CLIENT_ID>',
    clientSecret: '<YOUR_CLIENT_SECRET>',
    scope: 'create:passwords_tickets',
    headers: {
        'auth0-custom-domain': 'my-custom-domain.com'
    }
});

(async () => {
    try {
        const ticket = await auth0.tickets.changePassword({
            user_id: 'auth0|abc123',
            result_url: 'https://example.com/success'
        });
        console.log('Password change ticket created:', ticket.data.ticket);
    } catch (err) {
        console.error('Error creating password change ticket:', err);
    }
})();

Was this helpful?

Sample response: The custom domain is passed in the header used to generate the ticket URL.

{
    "ticket": "https://my-custom-domain.com/u/reset-verify?ticket=abc123"
}

Was this helpful?

Response messages

When you provide the auth0-custom-domain HTTP header, the following additional response types are possible:

HTTP status code	Message
`409`	The tenant has multiple verified custom domains.
`400`	The custom domain does not exist for the tenant.
`400`	The `auth0-custom-domain` HTTP header has an invalid format.

If you enable MCD and use the Auth0 Dashboard to configure Email templates, the Try feature will not allow you to test with a custom domain.

Multiple Custom Domains with Actions

Auth0 Actions allows you to create custom logic handling of your different transactions based on the custom domain.

For example, you could create an Action that directs a user to an associated Organization, or enforce a specific access control policy.

To facilitate this, post-login Actions features the object event.request.hostname, which provides the hostname being used for the authentication flow.

Use case: Restrict user access to an Organization based on custom domain

Store a domain allowlist and denylist (for example, allow_domains and deny_domains) in your Organization’s metadata.

Create an Action that:

Gets the user’s domain through the event.request.hostname property
Compares that domain with both lists
Allows or denies the user access accordingly

exports.onExecutePostLogin = async (event, api) => {

    console.log(`org ${event?.organization?.name} accessed from domain ${event?.request?.hostname}`);

    if (event?.organization?.metadata?.deny_domains && event?.organization?.metadata?.allow_domains) {
        console.warn(`[WARNING] configuration issue. org ${event?.organization?.name} has both deny_domains and allow_domains`);
    }

    // Check either deny (A) allow (B) not both

    // (A) checks org's deny_list
    const isDomainDenied = () =>
        (event?.organization?.metadata?.deny_domains ? event?.organization?.metadata?.deny_domains.split(',').map(d => d.trim()).includes(event?.request?.hostname) : false);

    if (isDomainDenied()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${event?.request?.hostname}`);
    }

    // (B) checks org's allow_list
    const isDomainAllowed = () =>
        (event?.organization?.metadata?.allow_domains ? event?.organization?.metadata?.allow_domains.split(',').map(d => d.trim()).includes(event?.request?.hostname) : false);

    if (!isDomainAllowed()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${event?.request?.hostname}`);
    }

};

Was this helpful?

MCD GA will introduce a new custom domain Action object, which will include custom domain metadata. Your Action code will need to be updated at GA if you use the new object.

Custom domain attributes

The MCD EA release introduces the following attributes related to custom domain verification and SSL/TLS certificate management. These additions provide granular insights into the provisioning and operational status of custom domains. Please be aware that the attributes and their descriptions outlined in this document are subject to change in future releases.

Updated attributes

Attribute	Description
`status`	A new enumeration value, `failed`, has been added to the `status` attribute. This value indicates that the custom domain verification process has encountered an error and was unsuccessful. This is in addition to the existing supported values `pending` and `ready`.

New attributes

The following attributes are supported for Auth0-managed domains only:

Attribute	Description
`verification.status`	Status of the DNS record verification process. Possible values are: `verified`, `pending`, and `failed`.
`verification.error_msg`	In the event that `verification.status` indicates a failure, this string attribute will contain a human-readable error message providing context for the verification failure.
`verification.last_verified_at`	This timestamp attribute records the date and time of the last successful verification of the custom domain. The format of this timestamp will adhere to ISO 8601.
`certificate`	This object encapsulates information related to the SSL/TLS certificate associated with the custom domain.
`certificate.status`	This attribute indicates the current provisioning status of the SSL/TLS certificate. Possible values will include states such as `provisioning`, `provisioned`, `provisioning_failed`, and `renewing_failed`.
`certificate.error_msg`	If the `certificate.status` is `provisioning_failed` or `renewing_failed`, this string attribute will provide a user-friendly error message detailing the reason for the failure.
`certificate.certificate_authority`	This string attribute specifies the Certificate Authority that issued the SSL/TLS certificate for the custom domain.
`certificate.renews_before`	For Auth0-managed custom domains, this new timestamp attribute indicates the date and time before which the SSL/TLS certificate must be renewed. The format of this timestamp will adhere to ISO 8601.