PingOne Advanced Identity Cloud

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 API endpoint

Advanced Identity Cloud provides the Custom Domains API endpoint 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 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 created with the fr:idc:custom-domain:* scope.

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

    $ 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. For example, alpha.
    3 Replace <access-token> with the access token.
    Show response 
    {
    "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.

  2. Adapt the custom domain configuration to suit your use case. Learn more in Configure customer-friendly domain names.

    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 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:

    $ 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. 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. 
    {
    "domains": [
        "customers.mycompany.co.uk",
        "customers.mycompany.com"
    ]
}
    Show response 
    {
    "domains": [
        "customers.mycompany.co.uk",
        "customers.mycompany.com"
    ]
}