---
title: Manage custom domains using the API
description: You can find background information on custom domains in PingOne Advanced Identity Cloud in Configure customer-friendly domain names.
component: pingoneaic
page_id: pingoneaic:realms:custom-domains-api
canonical_url: https://docs.pingidentity.com/pingoneaic/realms/custom-domains-api.html
section_ids:
  custom-domains-api-endpoint: Custom domains API endpoint
  authenticate-to-the-custom-domains-api-endpoint: Authenticate to the custom domains API endpoint
  view-custom-domains: View custom domains
  update-custom-domains: Update custom domains
---

# Manage custom domains using the API

You can find background information on custom domains in PingOne Advanced Identity Cloud in [Configure customer-friendly domain names](custom-domains.html).

## Custom domains API endpoint

Advanced Identity Cloud provides the [Custom Domains API endpoint](https://docs.pingidentity.com/pingoneaic/_attachments/api/#tag/Custom-Domains) to manage custom domains:

/environment/custom-domains/\<realm>

The custom domains API endpoint is realm specific, requiring one of the following realm identifiers:

| Realm identifier | Description                                   |
| ---------------- | --------------------------------------------- |
| `root`           | Top-level realm used by tenant administrators |
| `alpha`          | Alpha realm used by customers or employees    |
| `bravo`          | Bravo realm used by customers or employees    |

To view all the custom domains in your tenant environment, make three separate requests to the custom domains API endpoint, one for each realm identifier.

## Authenticate to the custom domains API endpoint

To authenticate to the custom domains API endpoint, use an [access token](../developer-docs/authenticate-to-rest-api-with-access-token.html) created with the following scope:

| Scope                    | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `fr:idc:custom-domain:*` | Full access to the custom domains API endpoint. |

## View custom domains

Make a GET request to the `/environment/custom-domains` endpoint to view the domains or subdomains that you can use to access a realm.

To view the custom domain configuration for a realm:

1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) created with the `fr:idc:custom-domain:*` scope.

2. Get the custom domain configuration from the `/environment/custom-domains` endpoint:

   ```shell
   $ curl \
   --request GET 'https://<tenant-env-fqdn>/environment/custom-domains/<realm>' \(1)(2)
   --header 'Authorization: Bearer <access-token>'(3)
   ```

   |       |                                                                                                                                                 |
   | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
   | **1** | Replace \<tenant-env-fqdn> with the FQDN of your tenant environment.                                                                            |
   | **2** | Replace \<realm> with one of the realm identifiers listed in [Custom domains API endpoint](#custom-domains-api-endpoint). For example, `alpha`. |
   | **3** | Replace \<access-token> with the access token.                                                                                                  |

   > **Collapse: Show response**
   >
   > ```json
   > {
   >     "domains": [
   >         "customers.mycompany.co.uk"
   >     ]
   > }
   > ```

## Update custom domains

Make a PUT request to the `/environment/custom-domains` endpoint to set or update the domains or subdomains that you can use to access a realm.

To update the custom domain configuration for a realm:

1. Review the existing custom domain configuration for the realm. Learn more in [View custom domains](#view-custom-domains).

2. Adapt the custom domain configuration to suit your use case. Learn more in [Configure customer-friendly domain names](custom-domains.html).

   |   |                                                                                                                                                      |
   | - | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | Before removing a domain or subdomain from the configuration, you must first update any existing applications that rely on that domain or subdomain. |

3. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) created with the `fr:idc:custom-domain:*` scope.

4. Replace the existing custom domain configuration with the custom domain configuration you adapted in step 2:

   ```shell
   $ curl \
   --request PUT 'https://<tenant-env-fqdn>/environment/custom-domains/<realm>' \(1)(2)
   --header 'Authorization: Bearer <access-token>' \(3)
   --header 'Content-Type: application/json' \
   --data '<custom-domains-configuration>'(4)
   ```

   |       |                                                                                                                                                                                                                                                                                                                                                                     |
   | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **1** | Replace \<tenant-env-fqdn> with the FQDN of your tenant environment.                                                                                                                                                                                                                                                                                                |
   | **2** | Replace \<realm> with one of the realm identifiers listed in [Custom domains API endpoint](#custom-domains-api-endpoint). For example, `alpha`.                                                                                                                                                                                                                     |
   | **3** | Replace \<access-token> with the access token.                                                                                                                                                                                                                                                                                                                      |
   | **4** | Replace \<custom-domains-configuration> with a JSON array of custom domains. For example, the following configuration adds a new subdomain `customers.mycompany.com` to the configuration example used in [View custom domains](#view-custom-domains).```json
   {
       "domains": [
           "customers.mycompany.co.uk",
           "customers.mycompany.com"
       ]
   }
   ``` |

   > **Collapse: Show response**
   >
   > ```json
   > {
   >     "domains": [
   >         "customers.mycompany.co.uk",
   >         "customers.mycompany.com"
   >     ]
   > }
   > ```