Archived Okta Identity Governance API changelog (2023-2024)

Note: See the latest Okta Identity Governance API release notes.

Contains a log of all API changes.

Breaking changes may only occur during the BETA lifecycle of an API, and will be minimized as much as possible.

2025.01.2

FIX - Added the scope okta.accessRequests.catalog.read to the OAuth 2.0 scopes

The okta.accessRequests.catalog.read scope, which allows apps to read information about Access Request catalogs in your Okta organization, now appears in the OAuth 2.0 Scopes (opens new window).

2025.01.1

FIX - Update the Request Condition didn't update name property

• The Update the Request Condition (opens new window) call didn't update the name property of the request condition.

FIX - Increased the max length to 7000 for user scope expression

• Increased the max length to 7000 characters for the property principalScopeSettings.userScopeExpression (opens new window) in the request body of the 'Create a campaign' (opens new window) operation.

2025.01.0

FEATURE - GA Select Okta Identity Governance APIs

• The following sets of APIs have transitioned from Beta to GA:

  • Campaigns
  • Reviews
  • Access Requests - V2
  • My Requests
  • My Catalogs

• Added EA Access Requests - V2 administrative APIs for:

  • 'List all entries for the default access request catalog' (opens new window)
  • 'Retrieve a catalog entry by an ID' (opens new window)

2024.12.1

FEATURE - New request status - EXPIRED

• The status of a request now includes a new EXPIRED value. See status (opens new window) and request domain model (opens new window).

FIX - Update to Create a Request API

• Setting the requestedBy parameter in the request body of the Create a Request API (opens new window) returned the default admin user ID in the response.

FIX - Update to Retrieve a Request API and Retrieve my Request API

• Updated the requesterFieldValues object for the Retrieve a Request API (opens new window) and the Retrieve my request API (opens new window). This object previously returned only the id and value properties.

2024.11.1

FIX - Update to Retrieve My Request API

• Updated the requesterFieldValues object for the Retrieve My Request API (opens new window). This object now contains the list of field values that were populated while submitting an Access Request.

2024.11.0

FEATURE - new Access Requests APIs

• At the left sidebar, split API reference into Management APIs and Enduser APIs.
• Added Access Requests - V2 administrative APIs for:
  • 'Create a request' (opens new window)
  • 'Create a request message' (opens new window)
  • 'Retrieve an entry's request fields' (opens new window).
  • 'List all Requests' (opens new window)
  • 'Retrieve a Request' (opens new window)
• Added End user APIs for:
  • 'Create a request' (opens new window)
  • 'Retrieve my request' (opens new window)
  • 'List all entries for the default access request catalog' (opens new window)
  • 'Retrieve an entry from my catalog' (opens new window)
  • 'Retrieve an entry's request fields' (opens new window)
  • 'List all my catalog entry users' (opens new window)
  • 'Retrieve a users request-fields for an entry' (opens new window)

FEATURE - Enhanced Group Remediation

• Added a new property in the 'Create a campaign' (opens new window) operation to accept /remediationSettings/autoRemediationSettings (opens new window).

FEATURE - Update to Campaigns API

• Updated the principalScopeSettings object for the Campaigns API (opens new window). This object now includes the predefinedInactiveUsersScope property that identifies the duration that users have not used single sign-on (SSO) to access their account within a specific time frame.

2024.10.0

FIX - Remove ENTITLEMENT_VALUES from access-scope settings for Access Request condition APIs

• Removed the ENTITLEMENT_VALUES from the access-scope settings from the following APIs:
  • 'Request conditions' (opens new window)
  • 'Request settings' (opens new window).

2024.09.0

FEATURE - OAuth2 scopes for Access Request conditions and requests APIs, first BETA release

• OAuth2 scopes for Access Requests condition and request APIs:
  • okta.accessRequests.condition.manage
  • okta.accessRequests.condition.read
  • okta.accessRequests.request.manage
  • okta.accessRequests.request.read

2024.08.0

FEATURE - New Access request condition APIs, first BETA release

• Added Access request V2 administrative APIs for:
  • 'Request conditions' (opens new window)
  • 'Request sequences' (opens new window)
  • 'Request settings' (opens new window).
• Access request V1 administrative APIs (Request types & Requests) remain unchanged.

2024.06.2

FEATURE - Added support to include only active users in the campaign

• Added a new property in the 'Create a campaign' (opens new window) operation to accept /principalScopeSettings/includeOnlyActiveUsers (opens new window).

2024.06.0

FIX - Update Admin Role Campaign Defaults

• Updated bulkDecisionDisabled (opens new window) to no longer be required for Admin Role campaigns.

2024.04.0

FEATURE - Added following Beta APIs for ENTITLEMENT MANAGEMENT feature

• Retrieve an entitlement (opens new window)
• List all entitlement values (opens new window)

DEPRECATE - List all entitlements will no longer return values

• To fetch values for a given entitlement, use List all values for an entitlement (opens new window) or List all entitlement values (opens new window)

FEATURE - Ability to create campaigns on Okta Admin Console for reviewing admin roles

• Updated the 'Create a campaign' (opens new window) operation to support governance for admin roles in resource-centric campaigns.

• Added support for 'justificationRequired' (opens new window) and 'bulkDecisionDisabled' (opens new window) and replaced 'isSelfReviewDisabled' (opens new window) with 'selfReviewDisabled' (opens new window)

• Also, these fields are now required to be marked as true for Admin Role campaigns.

FIX - OAuth2 scope documentation

• Fixed the documentation of required scopes for Request Types, Requests, and Teams operations to correct values.
  • Incorrect old documentation listed : okta.governance.accessRequest.manage , okta.governance.accessRequest.read
  • New correct documentation: okta.governance.accessRequests.manage, okta.governance.accessRequests.read

BETA - Breaking changes

FIX - Resource name and description is no longer populated in responses for ENTITLEMENT MANAGEMENT (opens new window) feature APIs (Entitlements, Entitlement Bundles, Grants, and Principal Entitlements)

2023.09.0

FEATURE - Added following Beta APIs for ENTITLEMENT MANAGEMENT (opens new window) feature

• Entitlement Bundles (opens new window)
• Entitlements (opens new window)
• Grants (opens new window)
• Principal Entitlements (opens new window)

FEATURE - Added support for certifying entitlement-enabled resources to 'Campaigns' (opens new window) and 'Reviews' (opens new window) Apis

'Create' (opens new window), 'List' (opens new window), 'Retrieve' (opens new window), 'Delete' (opens new window), 'Launch' (opens new window) and 'End' (opens new window) campaigns containing entitlement enabled resources.

'List' (opens new window), 'Reassign' (opens new window) and 'Retrieve' (opens new window) items reviewing app entitlements.

2023.08.0

FIX - startReview in 'Create a Campaign' is required

Fixed 'Create a campaign' (opens new window) operation to show /reviewerSettings/reviewerLevels/startReview (opens new window) as required field.

2023.07.0

DEPRECATE - /governance/api/v1/campaigns/{campaignId}/delete endpoint

Deprecated this endpoint in favour of 'Delete Campaign' (opens new window) to be consistent with other DELETE endpoints.

Existing /delete endpoint will continue to work until it is removed in future release.

2023.06.0

FEATURE - Ability to create recurring campaigns

Updated 'Create a campaign' (opens new window) operation to support defining a recurring schedule by allowing new types described in /scheduleSettings/type (opens new window). During creation of a campaign, you can provide the additional details described at /scheduleSettings/recurrence (opens new window) to setup the recurrence. These settings will also be reflected in 'List all campaigns' (opens new window) and 'Retrieve a campaign' (opens new window)

FEATURE - Ability to create campaigns with a group or group owner as reviewer

Updated 'Create a campaign' (opens new window) operation to support setting a Group or Group Owner as reviewer, as is currently supported in the UI by allowing new types described in /reviewerSettings/type (opens new window). During creation of a campaign, when defining the reviewer, new settings are available and described at /reviewerSettings/reviewerGroupId (opens new window). These settings will also be reflected in 'List all campaigns' (opens new window), 'Retrieve a campaign' (opens new window), 'List all reviews' (opens new window) and 'Retrieve a review' (opens new window)

FEATURE - Ability to create multi-level campaigns

Updated 'Create a campaign' (opens new window) to support Multi-level campaigns, as is currently supported in the UI, but allowing new types described in /reviewerSettings/type (opens new window). During creation of a campaign, you can provide multi-level reviewer details described at /reviewerSettings/reviewerLevels (opens new window). These settings will also be reflected in 'List all campaigns' (opens new window), 'Retrieve a campaign' (opens new window), 'List all reviews' (opens new window), 'Retrieve a review' (opens new window) and 'Reassign the reviews' (opens new window)

FEATURE - Ability to create user campaigns

Updated 'Create a campaign' (opens new window) operation to allow creation of User Campaigns, currently available as self-service EA in the UI, by allowing new types described in /principalScopeSettings/type (opens new window). During creation of a campaign, you can choose to create Resource Campaigns (the existing type) or User Campaigns, with settings described at /principalScopeSettings (opens new window). These settings will also be reflected in 'Retrieve a campaign' (opens new window)

FEATURE - Ability to create a message on a request

Added 'Create a message for a request' (opens new window) operation to allow creation of a message for an existing request.

2023.03.1

BETA - Breaking changes

FIX - reviewerSettings.type in 'Create a campaign' and 'Retrieve a campaign' operations

Fixed 'Create a campaign' (opens new window) and 'Retrieve a campaign' (opens new window) operations to properly accept and return the /reviewerSettings/type (opens new window) enum value REVIEWER_EXPRESSION instead of REVIEWER-EXPRESSION.

2023.03.0

Features

FEATURE - Resource owner approval type

Added the RESOURCE_OWNER value to the approvalType (opens new window) parameter for Create a request type (opens new window).

This update enables the creation of request types that require approvals from the owner of the resource specified in targetResources (opens new window).

Currently, Okta only supports a group resource, that is, when resourceSettings.type (opens new window) is GROUPS.

This change has no impact on any previously created request types.

2023.02.0

Fixes

FIX - An HTTP 500 Internal Server Error was returned for some operations

• Fixed the case when a Retrieve a request type (opens new window) would 500 if the accessDuration (opens new window) was controlled by a DATE-TIME field in a CUSTOM request type.

• Fixed the case when a Retrieve a request (opens new window) would 500 if an ADD_USER_TO_GROUP or ASSIGN_APP_TO_USER action failed to run, and then was manually closed by a team member.

2023.01.0

BETA - Breaking changes

FEATURE - Request type approval settings

Added new option NONE for approvalSettings.type (opens new window) for Create a request type (opens new window).

This enables the creation of request types that don't have any required approvals.

approvalSettings (opens new window) is now a required property. Attempting to create a request type without specifying approvalSettings (opens new window) will result in a 400 Bad Request response.

Allowing for this use case requires modification of the default value for approvalSettings (opens new window).

Integrations relying on the default specification of one approval by the requester's manager must now explicity specify approvalSettings.type (opens new window) of SERIAL and include a manager approval object when creating the request type.

Check below for an example of a request body that used to return a 200 response code, that will now return a 400 response code.

Example

{
    "name": "salesforce-01",
    "description": "How users can request access to Admin Group",
    "ownerId": "61eb0f06c462d20007f051ac",
    "resourceSettings": {
        "type": "GROUPS",
        "targetResources": [
            {
                "resourceId": "00g1emaKYZTWRYYRRTSK"
            }
        ]
    }
}

This change has no impact on any previously created request types.

• approvalSettings with no required approvers: {"type":"NONE"}

• with requester manager approver required: {"type":"SERIAL","approvals":[{"approverType":"MANAGER"}]}

FIX - createdBy in 'Retrieve a request' and 'List all requests' operations

Fixed 'Retrieve a request' (opens new window) and 'List all requests' (opens new window) operations to properly return the createdBy (opens new window) id of the authenticated user, which can be distinct from requesterUserIds (opens new window)

FIX - requesterFieldValues and approvals/0/fieldValues in 'Retrieve a request' operation

Fixed the data type of /requesterFieldValues/0/value (opens new window) in 'Retrieve a request' (opens new window) response body for fields of type DATE-TIME to match API reference.

• Old date time value :1665148010117

• New date time value per API reference: 2022-10-07T13:06:50.117Z

Features

• Added requesterFieldValues (opens new window) to Create a request (opens new window) operation request body. This enables creation of requests using a request type with required fields.

• Added approvalSettings.approvals.description (opens new window) to Create a request (opens new window) operation request body. This enables creation of a request types with description for required approvals.

• 'Retrieve a request' (opens new window) now returns a request with type ACCESS_REQUEST, and includes the approvals and actions objects. Prior to this change if a request was created using a request type with CUSTOM modifications in the administrative UI, the request had type CUSTOM which omitted the approvals and actions objects.

Note: While there are aspects of requests based on CUSTOM request types which may not be represented in API responses, the actions and approvals information included in the API response are now reliable.

Fixes

• Fixed 'Retrieve a request' (opens new window) and 'List all requests' (opens new window) operations to properly return the createdBy (opens new window) id of the authenticated user, which can be distinct from requesterUserIds (opens new window).
• Fixed handling of a number of invalid HTTP requests to properly return 4xx status codes instead of 500.

Documentation updates

• Added changelog
• Clarified documentation of accessDuration (opens new window) property in Create a request type (opens new window) body to indicate we only support durations which contain minutes, not months.