> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to use the Custom Domain Hook with the Delegated Administration Extension.

# Delegated Administration: Custom Domain Hook

When using [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains) with the Delegated Administration Extension, the **Custom Domain Hook** allows you to specify which custom domain should be used for user operations such as creating users, resetting passwords, verifying emails, and blocking users.

## Hook contract

* **ctx**: Context object containing information about the current request.
  * **method**: The operation being performed (e.g., `create`, `reset_password`, `verify_email`, `block_user`).
  * **payload**: Data related to the operation (for `create` method, contains user details like email).
  * **request**: Contains information about the request.
    * **originalUser**: The user being operated on (for methods other than `create`).
* **callback(error, result)**: Callback function to return the custom domain configuration.
  * **error**: Error object if something went wrong, otherwise `null`.
  * **result**: Object specifying the custom domain behavior:
    * **customDomain** (string): The custom domain to use (e.g., `'customone.example.com'`).
    * **useCanonicalDomain** (boolean): Set to `true` to use the tenant's canonical domain instead of a custom domain.
    * Return empty object `{}` to delegate to the tenant's [default domain](/docs/customize/custom-domains/multiple-custom-domains).

## Supported methods

The Custom Domain Hook is invoked for the following user operations:

* **create**: When creating a new user
* **reset\_password**: When sending a password reset email
* **verify\_email**: When sending an email verification link
* **block\_user**: When blocking a user

## Sample use

In this example, users from different email domains are routed to different custom domains. Users from a corporate domain use the canonical tenant domain, while all others use the tenant's default domain.

```javascript lines theme={null}
function(ctx, callback) {
  // Map email domains to custom domains
  const emailToDomain = {
    'customone.com': 'customone.example.com',
    'customtwo.com': 'customtwo.example.com',
  };

  // Helper to extract custom domain from email
  function getDomainFromEmail(userEmail) {
    if (!userEmail) return null;
    const domain = userEmail.split('@')[1];
    return emailToDomain[domain];
  }

  // Helper to determine if canonical domain should be used
  function shouldUseCanonical(userEmail) {
    if (!userEmail) return false;
    const domain = userEmail.split('@')[1];
    return domain === 'corp.com';
  }

  // Get user email based on the operation
  let userEmail;
  if (ctx.method === 'create') {
    // For create operations, email is in the payload
    userEmail = ctx.payload.email;
  } else {
    // For other operations, get email from the original user
    userEmail = ctx.request.originalUser.email;
  }

  const customDomain = getDomainFromEmail(userEmail);

  // Option 1: Use a specific custom domain
  if (customDomain) {
    return callback(null, {
      customDomain: customDomain
    });
  }

  // Option 2: Use the canonical tenant domain
  if (shouldUseCanonical(userEmail)) {
    return callback(null, {
      useCanonicalDomain: true
    });
  }

  // Option 3: Use tenant's default domain (if configured)
  // Return empty object to delegate to the default domain
  return callback(null, {});
}
```

## Notes

* If this hook is not configured, the Delegated Administration Extension will use the tenant's default custom domain if one is configured, or the canonical domain otherwise.
* The custom domain returned must be a verified custom domain configured in your tenant. If you specify an invalid or unverified domain, the operation will fail.
* When using `useCanonicalDomain: true`, emails and links will use your Auth0 tenant's canonical domain (e.g., `YOUR_TENANT.auth0.com` or `YOUR_TENANT.REGION.auth0.com`).
* Returning an empty object `{}` delegates the domain selection to the tenant's [default custom domain](/docs/customize/custom-domains/multiple-custom-domains) configuration.

## Learn more

* [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains)
* [Delegated Administration: Access Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook)
* [Delegated Administration: Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook)
* [Delegated Administration: Write Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook)
* [Delegated Administration: Settings Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook)