Launch a security access review

This guide shows you how to launch a security access review using the Okta Identity Governance (OIG) APIs. You can trigger a security access review from your custom app code or from delegated flows in Okta Workflows (opens new window) using the APIs. Reviews are performed from the Okta Security Access Review app.

Learning outcomes

Learn how to set up Okta to access Okta Identity Governance APIs (opens new window).
Learn how to trigger a security access review using the Okta Identity Governance (opens new window) > Security Access Review (opens new window) APIs.

What you need

An Okta org that's subscribed to OIG
Postman (or a similar tool to follow this guide and test the OIG APIs)

Overview

Security access reviews offer a unified tool for reviewing and responding to access privileges for a specific user. This is particularly useful when responding to a security event or an identity threat on a user. The security access review is a snapshot of a user's resource access at the time of creation. It also provides an AI-generated summary for reviewers to quickly assess high-risk accesses and anomalies.

Several reviewers (Okta end users) can be assigned to a security access review for assessment coverage when app security is provided by different owners. Assigned reviewers can immediately act on fine-grain remediation beyond terminating a user's session, such as revoking access to a specific resource or entitlement.

Security access review flow

Security access reviews are launched through your custom app code or through a delegated Workflow sequence using the APIs. The reviews are intended to be triggered from a security or policy evaluation event that focuses on a particular user. Only principals that are assigned the super admin role or a custom admin role (with required permissions) can trigger and view all security access reviews.

After the security access review is generated, an email is sent to designated reviewers, notifying them to review a user's access. The designated reviewers are assigned to the Okta Security Access Review app, where they conduct the review. Reviewers are only able to view and act on items in the security access review for which they have permissions.

See the Security Access Reviews (opens new window) product documentation for more information.

Notes:

Security admins can also launch security access reviews manually from the Admin Console, but this isn't the typical process flow. See Create a security access review (opens new window) in the product documentation.

For scheduled, broader-scoped access reviews, use Access Certifications campaigns. See Campaigns (opens new window). These access reviews are more appropriate for compliance audits.

This guide shows you how to launch a security access review using the APIs with OAuth 2.0 authentication:

Set up Okta for API access.
Launch a security access review.
Conduct a security access review.

Set up Okta for API access

Set up Okta so that you can authenticate to Okta APIs and have the proper roles and permissions for security access reviews.

You only have to set up your Okta org for OIG Security Access Reviews API access once. Okta recommends that you perform these tasks from the Admin Console. However, you can also use Okta Management APIs (opens new window) for the same tasks.

Note: See the Use Okta Identity Governance API in Okta Workflows (opens new window) article for an overview of how to use Okta Workflows with OIG APIs.

Create a custom admin role for security access reviews

Only super admins (SUPER_ADMIN) can initially trigger security access reviews in Okta Identity Governance orgs.

For least-privilege access, Okta recommends that you create a custom role for admins to manage security access reviews. See Create a role (opens new window) and assign following permissions to your custom role:

Manage security access reviews as admin (okta.governance.securityAccessReviews.admin.manage)
View users (okta.users.read)

You need to assign the custom admin role to the principal that manages security access reviews. Principals can be an Okta user or a client app (service app). With the proper roles in place, these principals have the permissions required to trigger and review security access reviews.

Create an app for OAuth 2.0 authentication

Access OIG APIs by authenticating with an OAuth 2.0 access token (opens new window). To obtain an OAuth 2.0 access token for API authentication, you need to have an app in Okta for API access. The app provides you with the client ID and secret (or credentials) to request for access tokens.

If you already have an OIDC or service app for API authentication, ensure that your app is granted with the following OAuth 2.0 scopes:

okta.governance.securityAccessReviews.admin.manage
okta.users.read

In addition, grant any other scopes that you may need for other API requests, such as okta.apps.manage.

Also ensure that your API users or service app are assigned to the IAM admin role that has permission to manage security access reviews. Assign either:

The super admin (SUPER_ADMIN) role

Or
Your custom admin role (with the okta.governance.securityAccessReviews.admin.manage and okta.users.read permissions).

Note: If you're using Okta Workflows, the Okta Workflows OAuth app in your org is used for API authentication. Grant the okta.governance.securityAccessReviews.admin.manage and the okta.users.read scopes to this app. See Authorization > Create a connection from the current Okta org (opens new window).

If you don't have an app for API access:

Create an OIDC-OpenID Connect sign-in method app for API access if you're making API requests as an Okta user.

See User-based API access setup (opens new window) to create an OIDC app. Grant the required okta.governance.securityAccessReviews.admin.manage and okta.users.read scopes to the OIDC app (in addition to any other scopes you may need).

Assign the API users to the OIDC app. Ensure that the API users are assigned to the super admin role or to a custom role that is granted the following permissions:
- Manage security access reviews as admin (okta.governance.securityAccessReviews.admin.manage)
- View users (okta.users.read)
Create an API Services sign-in method app for API access if you're making API requests from a service or daemon without user context.

See Service-based API access setup (opens new window) to create a service app. Grant the required okta.governance.securityAccessReviews.admin.manage and okta.users.read scopes, and assign the required admin role (super admin or your custom role) to the service app.

Launch a security access review

The POST /governance/api/v2/security-access-reviews API method (Create a security access review (opens new window)) is used to launch the security access review. A custom app or a delegated flow uses the API to launch the review following a security or policy evaluation event.

Note: Security admins can also launch security access reviews manually from the Admin Console, but this isn't the typical process flow. See Create a security access review (opens new window) in the product documentation.

See the API request examples in the following sections to launch a security access review.

Get an OAuth 2.0 access token

You can use Okta authentication SDKs or code your own sequence to get an access token for API access.

Note: See getToken methods from Okta authentication SDKs (opens new window). For example, use tokenManager.getTokens() (opens new window) in Okta Auth JavaScript SDK (opens new window).

For API requests from a user, see Get an access token and make a request (opens new window).
For API requests from a service app, see Get an access token from a signed JWT (opens new window).

Use the obtained OAuth 2.0 access token as bearer tokens in the authentication header of your API requests.

Note: This task isn't required for delegated flow implementations. The Okta Workflows OAuth app handles OAuth 2.0 access to APIs. See Create a connection from the current Okta org (opens new window) and Custom API Actions (opens new window).

Get IDs for your users

Use Okta user IDs as parameters to initiate a security access review using the POST /governance/api/v2/security-access-reviews method (see Create a security access review (opens new window)).

Find the Okta user IDs for the following users:

The target user for the security access review (for the principalId parameter). This is the user whose access is under review.
The reviewers for the security access review (for the reviewerSettings.userSettings parameter).

These are the security analysts or resource owners that assess the user access items and perform any remediation. Reviewers can be an Okta admin or an end user. After the review is created, reviewers are automatically assigned the Okta Security Access Review app to conduct the review.

Use the List all user (opens new window) request with the search query parameter and user profile attributes to find the user IDs.

Note: This request requires the okta.users.read scope.

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {yourOktaAccessToken}" \
"https://${yourOktaDomain}/api/v1/users?search=profile.login%20eq%20%22testUser%40example.com%22"

Use the id property of the response payload for the user ID parameters in the Create a security access review (opens new window) request.

See User query options (opens new window) for more query options.

Create a security access review

Create a security access review with the Create a security access review (opens new window) request (POST /governance/api/v2/security-access-reviews).

Note: The targeted user of the security access review can't be a reviewer. An API error is returned if you specify the same ID in principalId as one of the IDs in the reviewerSettings.userSettings.includeUserIds list.

Request example


curl -i -X POST \
  https://{yourOktaDomain}/governance/api/v2/security-access-reviews \
  -H 'Authorization: Bearer {yourOktaAccessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "principalId": "00ucpjbi6JMmDvdN40g4",
    "name": "Security access review for Test user",
    "reviewerSettings": {
      "type": "USER",
      "userSettings": {
        "includedUserIds": [
          "00ucpjbi6JMmDvdN40g4",
          "00ucpjbi6JMmDvdN40g5"
        ]
      }
    }
  }'

Response example

{
    "id": "sar1lo5X9wmNTFX7x0g4",
    "createdBy": "00ucfd4IQoH6YBZgA0g4",
    "created": "2025-08-19T22:10:34Z",
    "lastUpdated": "2025-08-19T22:10:34Z",
    "lastUpdatedBy": "00ucfd4IQoH6YBZgA0g4",
    "_links": {
        "securityAccessReviewDetails": {
            "href": "https://myoktadomain.okta.com/governance/api/v2/security-access-reviews/sar1lo5X9wmNTFX7x0g4",
            "hints": {}
        }
    },
    "status": "PENDING",
    "name": "Security access review for Test user",
    "endTime": "2025-08-26T22:10:33.882Z",
    "reviewerSettings": {
        "type": "USER",
        "userSettings": {
            "includedUserIds": [
                "00ucpjbi6JMmDvdN40g4",
                "00ucpjbi6JMmDvdN40g5"
            ]
        }
    }
}

The status of the security access review is PENDING when it's triggered. After the review is generated, the status is ACTIVE for reviewers to assess and act on the target user's granted access.

If the reviewer has never conducted a security access review before, the Okta Security Access Review app is automatically assigned to them after the review is generated. Reviewers can only view items in the access review that they have permission to view. For example, they can't view the System Log entries for the targeted user if they don't have permission to view System Logs.

For best practices, considerations, and limitations, see Security Access Review (opens new window).

Next steps: review and remediation

Reviewing and managing security access reviews through the APIs aren't covered in this guide. Okta recommends that reviewers use the Okta Security Access Review app for these operations. See Manage security access reviews (opens new window) and Review access (opens new window) in the product documentation.

For a complete list of available security access review APIs, see Security Access Reviews (opens new window) and My Security Access Review (opens new window).

Note: You can customize security access review notification emails. See securityAccessReviewReviewerNotification, securityAccessReviewClosingOneDayNotification, and securityAccessReviewEndNotification templates in Use customizable email templates. Also see ${securityAccessReview.*} variables in Use VTL variables.

Edit This Page On GitHub

On this page

Launch a security access review

Learning outcomes

What you need

Overview

Security access review flow

Set up Okta for API access

Create a custom admin role for security access reviews

Create an app for OAuth 2.0 authentication

Launch a security access review

Get an OAuth 2.0 access token

Get IDs for your users

Create a security access review

Request example

Response example

Next steps: review and remediation