Create Organization Domains

Learn how to create or delete Organization Discovery Domains using the Auth0 Dashboard and Management API.

Organization Discovery Domain is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement.

Use Organization domains during the login flows to include a prompt for users to choose the correct Organization. When configured, verified domains help Auth0 detect a user’s organization automatically or narrow organization options when users enter their email address.

To learn more, read Login Flows for Organizations.

Create an Organization domain

Create Organization domains in the Auth0 Dashboard or with the Auth0 Management API.

Auth0 Dashboard

To create an Organization domain in the Auth0 Dashboard:

1. Navigate to Auth0 Dashboard > Organizations.
2. Select the Domains tab.
3. Choose Add Domain.
4. Enter the domain information and status.
5. Select Add Domain.

Field	Description
Domain	Domain Email to associate for organization discovery (for example, Travel0.com). Must be a valid domain format. Defaults to pending until ownership is confirmed.

Management API

Find your Auth0 domain

Your Auth0 domain is your tenant name, your regional subdomain, and auth0.com, unless your tenant was created before June 2020 in the US region.

Example: If your tenant name is Travel0 and your region US, then your Auth0 domain is travel0.us.auth0.com. If your tenant was created before June 2020 in the US region, then your domain name would be https://travel0.auth0.com.

If you have a custom domains configured and verified in Auth0 Dashboard, your domain is your custom domain name. To learn more, read Custom Domains.

Call the Management API Create Organization Discovery Domain endpoint. Ensure you replace the placeholder values with the appropriate values from your tenant.

curl --request POST \
  --url 'https://{yourDomain}/api/v2/organizations/{ORGANIZATION_ID}/discovery-domains' \
  --header 'authorization: Bearer {MGMT_API_ACCESS_TOKEN}' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '{
    "domain": "{DOMAIN}",
    "status": "{STATUS}"
  }'

Placeholder	Description
MGMT_API_ACCESS_TOKEN	Access Token for Management API with the scope create:organization_discovery_domains.
ORGANIZATION_ID	ID of the organization to which you want to add the discovery domain (e.g., org_abc123).
DOMAIN	Required. Email domain you want to associate for Organization Discovery (for example, example.com).
STATUS	Optional. Initial status for the domain. Common values: pending, verified.

Status code	Error description	Message	Cause
201		Discovery domain successfully created. The domain record was added to the organization.
400	invalid_body	Invalid request body. The message will vary depending on the cause.	The request payload is not valid.
400	invalid_query_string	Invalid query string. The message will vary depending on the cause.	The query string is not valid.
401		Invalid token.
403	insufficient_scope	Insufficient scope; expected any of: create:organization_discovery_domains.	Tried to write a field that is not allowed with provided bearer token scopes.
409	conflict	An organization domain with the same name already exists.	An organization domain with the same name already exists.
429		Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.