---
title: Manage cookie domains using the API
description: You can find background information on cookie domains in PingOne Advanced Identity Cloud in Control cookie scope for custom domains.
component: pingoneaic
page_id: pingoneaic:realms:cookie-domains-api
canonical_url: https://docs.pingidentity.com/pingoneaic/realms/cookie-domains-api.html
section_ids:
  cookie-domains-api-endpoint: Cookie domains API endpoint
  authenticate-to-the-cookie-domains-api-endpoint: Authenticate to the cookie domains API endpoint
  view-cookie-domains: View cookie domains
  update-cookie-domains: Update cookie domains
---

# Manage cookie domains using the API

You can find background information on cookie domains in PingOne Advanced Identity Cloud in [Control cookie scope for custom domains](cookie-domains.html).

## Cookie domains API endpoint

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

## Authenticate to the cookie domains API endpoint

To authenticate to the cookie 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:cookie-domain:*` | Full access to the cookie domains API endpoint. |

## View cookie domains

Advanced Identity Cloud always writes cookies to your default tenant FQDN to ensure you retain access. Make a GET request to the `/environment/cookie-domains` endpoint to view the other domains or subdomains where your tenant environment writes cookies.

To view the cookie domain configuration in any tenant environment:

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

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

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

   |       |                                                                      |
   | ----- | -------------------------------------------------------------------- |
   | **1** | Replace \<tenant-env-fqdn> with the FQDN of your tenant environment. |
   | **2** | Replace \<access-token> with the access token.                       |

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

## Update cookie domains

Advanced Identity Cloud always writes cookies to your default tenant FQDN to ensure you retain access. Make a PUT request to the `/environment/cookie-domains` endpoint to set or update the other domains or subdomains where your tenant environment writes cookies.

To update the cookie domain configuration in any tenant environment:

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

2. Adapt the cookie domain configuration to suit your use case. Learn more in [Control cookie scope for custom domains](cookie-domains.html).

   |   |                                                                                                                                                                        |
   | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | Before removing a domain or subdomain from the configuration, you must first update any existing applications that rely on cookies set using 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:cookie-domain:*` scope.

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

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

   |       |                                                                                                                                                                                                                                                                                                                                                                                                  |
   | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
   | **1** | Replace \<tenant-env-fqdn> with the FQDN of your tenant environment.                                                                                                                                                                                                                                                                                                                             |
   | **2** | Replace \<access-token> with the access token.                                                                                                                                                                                                                                                                                                                                                   |
   | **3** | Replace \<cookie-domains-configuration> with a JSON array of cookie domains; for example, the following configuration adds a new subdomain `account.mycompany.co.uk` to the configuration example used in [View cookie domains](#view-cookie-domains).```json
   {
       "domains": [
           "sso.mycompany.co.uk",
           "banking.mycompany.co.uk",
           "account.mycompany.co.uk"
       ]
   }
   ``` |

   > **Collapse: Show response**
   >
   > ```json
   > {
   >     "domains": [
   >         "sso.mycompany.co.uk",
   >         "banking.mycompany.co.uk",
   >         "account.mycompany.co.uk"
   >     ]
   > }
   > ```

   An asynchronous process updates the environment's cookie domain configuration. This process can take up to 10 minutes to complete.