PingOne Advanced Identity Cloud

Manage cookie domains using the API

For background on cookie domains, learn more in Cookie domains.

Advanced Identity Cloud provides the Cookie Domains API endpoint to manage cookie domains.

To authenticate to the cookie domain API endpoint, use an access token created with the following scope:

Scope Description

fr:idc:cookie-domain:*

Full access to the cookie domain API endpoint.

Advanced Identity Cloud always writes session cookies to your default tenant FQDN to ensure you retain access. Use the /environment/cookie-domain endpoint to view the other domains or subdomains to which your tenant environment writes session cookies.

To view the cookie domain configuration in any tenant environment:

  1. Get an access token created with the fr:idc:cookie-domain:* scope.

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

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

Advanced Identity Cloud always writes session cookies to your default tenant FQDN to ensure you retain access. Use the /environment/cookie-domain endpoint to set the other domains or subdomains to which your tenant environment writes session cookies.

To update the cookie domain configuration in any tenant environment:

  1. Review the existing cookie domain configuration. Learn more in in View cookie domains.

  2. Adapt the cookie domain configuration to suit your use case. Learn more in Cookie domains.

    If you intend to remove 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 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:

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

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