Time Zone Configuration API for Identity Security Cloud tenants

[#1]

By default, all Identity Security Cloud sites, also known as orgs, have an org time zone set to CST/CDT. This org time zone affects a number of system internal task schedules that run regularly, such as the periodic nightly refresh. For more on time zones, see Time Zones in Identity Security Cloud.

At this time, there is not a way to update the tenant time zone in the User Interface (UI). You can change the org time zone using the Org Config APIs explained below. Setting the timeZone for an org will cause task schedules for the org to use that time zone instead of the default (CST).

NOTES:

• The time zone applies to the Identity Security Cloud site rather than the time zone of any user of the system. For example, if you have headquarters in Austin you might set your time zone to Central time. Remote users in California would need to be aware that the times they are working with are based on CST to adjust by 2 hours accordingly.
• The time zone settings are just one facet of the Org Configuration API which enables a customer administrator to access and set Org configuration field values.  Additional options might become available at a later date. Initially, access to this API is provided via REST endpoints as detailed herein, and no user interface is provided for these endpoints.

• Get Org Configuration Settings
• Set Org Time Zone
• List Valid Time Zone Values
• Example API Invocations
• Get Org Configuration Settings Example
• Set Org Time Zone Example
• Get Valid Time Zones Example

Prerequisites

• Authentication through the API Gateway, which returns a Java Web Token (JWT). This token is used to provide Bearer token authentication for subsequent calls to the configuration API endpoints. For more information about JWT authentication, see REST API Authentication​.

• Get Valid Time Zones requires a user permission level of Admin with scopes: idn:org-configs:read, idn:org-configs-user:read

• Get Org Config Settings requires Admin user level permissions with scopes: idn:org-configs:read, idn:org-configs:manage

• To set an Org Time Zone with Patch org config, you must have Identity Security Cloud Admin user level permissions with scopes: idn:org-configs:manage.

NOTES:

• Any given JWT will expire after a preset time period, requiring re-authentication​. For more information about JWT authentication, see REST API Authentication​.
• The examples below use a command line approach with cURL. Consult the API specs for other ways to leverage these APIs.

Get Org Configuration Settings

            GET      v2026/org-config

Set Org Time Zone

            PATCH  v2026/org-config  <org config patch json>

List Valid Time Zone Values

            GET      v2026/org-config/valid-time-zones

Example API Invocations

In the following examples, <org> is the org name and <JWT string> is the generated JWT for a valid API client user.

Get Org Configuration Settings Example

The user for the JWT in the following invocation is required to be either an Identity Security Cloud administrator or a cert-admin.

Command Line Invocation:

    curl -v "https://<org>.api.identitynow.com/v2026/org-config" -H "Authorization: Bearer <JWT string>"

Result:

  {"orgName":"<org>","timeZone":"America/Chicago"}

Set Org Time Zone Example

The user for the JWT in the following invocation is required to be an Identity Security Cloud administrator.

Command Line Invocation:

   curl -X PATCH -d '[{ "op": "replace", "path": "/timeZone", "value": "America/Chicago" }]' -v "https://<org>.api.identitynow.com/v2026/org-config" -H "Content-Type:application/json-patch+json" -H "Authorization: Bearer <JWT string>"

Result:

   {"orgName":"<org>","timeZone":"America/Chicago"}

Get Valid Time Zones Example

The user for the JWT in the following invocation may be any valid user.

Command Line Invocation:

    curl -v "https://<org>.api.identitynow.com/v2026/org-config/valid-time-zones" -H "Authorization: Bearer <JWT string>"

Result:

   ["Asia/Aden","America/Cuiaba","Etc/GMT+9","Etc/GMT+8","Africa/Nairobi","America/Marigot","Asia/Aqtau","Pacific/Kwajalein","America/El_Salvador","Asia/Pontianak","Africa/Cairo", ...]

NOTE: The very long result value list is abbreviated here.