Time Zone Configuration API

[#1]

By default, all IdentityNow 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 IdentityNow.

You can change the org time zone using the APIs defined 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 IdentityNow 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 Best Practices: IdentityNow REST API Authentication​.

• List Valid Time Zone Values can be run by any IdentityNow user.

• To run Get Org Configuration, you must be signed in to IdentityNow and strongly authenticated into the Admin interface. You can be either an IdentityNow administrator or a cert-admin.

• To run Set Org Time Zone, you must be signed in to IdentityNow and strongly authenticated into the Admin interface as an IdentityNow administrator.

NOTES: Any given JWT will expire after a preset time period, requiring re-authentication​. For more information about JWT authentication, see Best Practices: IdentityNow REST API Authentication​.

Get Org Configuration Settings

            GET      beta/org-config

Set Org Time Zone

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

List Valid Time Zone Values

            GET      beta/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 IdentityNow administrator or a cert-admin.

Command Line Invocation:

    curl -v "https://<org>.api.identitynow.com/beta/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 IdentityNow administrator.

Command Line Invocation:

   curl -X PATCH -d '[{ "op": "replace", "path": "/timeZone", "value": "America/Chicago" }]' -v "https://<org>.api.identitynow.com/beta/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/beta/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.