PingOne Advanced Identity Cloud

Identity Governance-related APIs

Identity Governance has many features, including access requests, the governance glossary (catalog), and entitlements. The following sections comprehensively explore the Identity Governance REST API endpoints.

YAML file

The REST APIs contain many parameters and, in some instances, large request bodies. For your convenience, you can view the entire API using a YAML file based on the OpenAPI specification.

To download the YAML file, click here.

Adjust the configurations of the file to match your specific details, such as your Advanced Identity Cloud tenant FQDN.

Endpoints

Access request

In Identity Governance, end users can request access to resources. Resources are target applications, entitlements, or roles. You define which resources are requestable.

For more information, refer to access requests.

The following table shows the endpoints used by access requests:

You can define workflows for access requests, such as what email gets sent to who for an access request type. These endpoints are used, in tandem, with the access request endpoints. For more information, refer to Workflows.
URI HTTP method Description

/governance/requests

POST

Create or validate a new access request for a list of users. When submitting a new request for access, the system validates the request’s contents. If no issues are found, IGA creates a request for each pairing of user and catalog items included in the request.

You can choose to only validate the request by using the validate action. This action displays any errors in the current request payload without creating any requests.

/governance/requests/requestId

GET

Retrieve the details of a single access request using an unique identifier, requestId.

/governance/requests/requestId

POST

Perform various actions on a specific request, such as:

  • approve

  • cancel

  • comment

  • modify

  • reassign

  • reject

  • update

Depending on the information the caller provides, each action has different request payloads.

/governance/user/userId/requests

GET

Get access requests based on the permissions the user has without additional filtering.

For additional search capabilities, use the POST /governance/user/{userId}/requests?_action=search API.

/governance/user/userId/requests

POST

Retrieve access requests submitted to review based on the permissions the user has with filtering.

Use the targetFilter property in the API payload to filter the requests based on desired criteria.

/governance/user/userId/approvals

POST

Get access requests the authenticated user needs to make a decision on either through a role or through a delegate.

Use the targetFilter property in the API payload to filter the requests based on desired criteria.

Governance glossary (catalog)

In Identity Governance, you can use the governance glossary to attach custom attributes (metadata) to applications, entitlements, or roles to enhance certifications or access requests.

For more information, refer to the Manage governance glossary.

The following table shows the endpoints used by access requests:

URI HTTP method Description

/governance/catalog

GET

Retrieve all resources in the access catalog without additional filtering. Each entry represents a single type of requestable access that you can add to a request. The supported types of access that are requestable are application, entitlement, and role.

/governance/catalog

POST

Get a list of resources (catalog items) with additional filtering. Each entry represents a single type of requestable access that you can add to a request. The supported types of access that are requestable are application, entitlement, and role.

/governance/search/schema

GET

Retrieve configured properties that are eligible for searching and sorting when querying the access catalog. Each property includes metadata, such as whether the property is multi-valued and its data type.

/governance/search/schema/objectType

GET

Retrieve configured properties that are eligible for searching and sorting when querying access catalog for a single given object. For example, entitlement specific properties you can use to search. Each property includes metadata, such as whether the property is multi-valued and its data type.

Provisioning

In the Advanced Identity Cloud admin UI, you can add or remove, or provision, resources from end users, however; you can do the same through REST APIs.

The following table shows the endpoints to add or remove users from resources:

URI HTTP method Description

/governance/user/userId/applications

POST

Add or remove applications for an end user.

/governance/user/userId/approvals

POST

Get requests the authenticated user is assigned, either directly, through a role, or through a delegate. You can use the targetFilter property in the API payload to filter requests based on the desired criteria.

/governance/user/userId/requests

GET

Get requests for which the authenticated user has permissions to view.

/governance/user/userId/roles

POST

Add or remove roles for an end user.

/governance/user/userId/entitlements

POST

Add or remove entitlements for an end user.

/governance/user/userId/tasks

GET

Get the tasks for which the authenticated user has permissions to view.

Identity Governance configurations

Identity Governance has overarching configurations, such as requiring a justification when rejecting an access request.

The following table shows the endpoints relating to Identity Governance configurations:

URI HTTP method Description

/commons/config

GET

Reads and returns all Identity Governance configuration properties across all categories.

Only access request-related properties are available. These properties are used to determine the behavior behind functionality. For example, access request features contain configuration on whether justification is required to reject a request or whether a user can approve their own access.

/commons/config

PUT

Update the configuration properties across all categories. Only access request-related properties are available.

You must include all current configurations when saving changes, Identity Governance replaces any omitted keys with default values.

/commons/config/key

GET

Get Identity Governance access request configurations for a given key (for example, iga_access_request).

/commons/config/key

PUT

Update Identity Governance access request configurations for a given key (for example, iga_access_request).

Account

Accounts are user profiles in applications. For example, when you provision an end user to an application, an account is created for them.

The following table shows the endpoints for accounts:

URI HTTP method Description

/governance/account

GET

Retrieve all account objects across all applications that have been onboarded as part of any application.

/governance/account

POST

Retrieve account objects searching by application, user, or glossary data.

/governance/account/accountId

GET

Retrieve a single account by ID.

/governance/account/accountId/glossary

GET

Retrieve an account’s glossary (catalog) metadata by account ID.

/governance/account/accountId/glossary

POST

Create glossary metadata for an account by account ID.

/governance/account/accountId/glossary

PUT

Create or Update an account’s glossary metadata by account ID.

Events

Events are rules defined to detect a change in the IGA system. Each rule has two core parts: a condition for the event and the action taken when that event occurs

The following table shows the endpoints for events:

URI HTTP method Description

/governance/event

GET

Get and search for a list of event rules defined in IGA. Each entry represents a single event rule defined to detect a change in the system. IGA rules consist of two core pieces: condition for the event, and action taken when the event occurs. For example, a rule might define that whenever someone creates a user in IGA, they should also generate a certification for that user.

/governance/event

POST

Create a single IGA event rule. A single event rule is defined to detect a change in the system. IGA rules consist of two core pieces: condition for the event, and action taken when that event occurs. For example, a rule might define that whenever someone creates a user in IGA, they should also generate a certification for that user.

/governance/event/id

GET

Get a single IGA event by id. The response is a single event rule defined to detect a change in the system.

/governance/event/id

PUT

Update a single IGA event by id. This call requires that the entire object be provided and that it replaces the entire existing event definition.

/governance/event/id

PATCH

Update a single IGA event by id. This call allows the caller to update specific properties of the event only without providing the entire object.

/governance/event/id

DELETE

Delete a single IGA event by id.

/governance/event/entity

GET

Get the list of available entities from which you can define a condition.

/governance/event/entity/object

GET

Get the available schema for defining a condition on a given object. For example, user returns the attributes available for defining an event for users in IGA.

Scope

Scope determines which specific users are able to view or interact with particular target objects. Scoping rules comprise of two core parts: a condition for the source object (who or what the scope applies to) and a condition for the target object that can be viewed or acted upon.

URI HTTP method Description

/governance/scope

GET

Get and search for a list of scoping rules defined in IGA. Each entry represents a single scoping rule defined to assign a set of conditions that allows a subset of users visibility on a subset of target objects. IGA scoping rules consist of two core parts: a condition for the source object (who/what the scope applies to) and a condition for the target object that can be viewed or acted upon.

/governance/scope

POST

Create a single scoping rule in IGA. Each scoping rule is defined to assign a set of conditions that allows a subset of users visibility on a subset of target objects. IGA scoping rules consist of two core parts: a condition for the source object (who/what the scope applies to) and a condition for the target object that can be viewed or acted upon.

/governance/scope/id

GET

Get a single scoping rule in IGA by ID. Each scoping rule is defined to assign a set of conditions that allows a subset of users visibility on a subset of target objects. IGA scoping rules consist of two core parts: a condition for the source object (who/what the scope applies to) and a condition for the target object that can be viewed or acted upon.

/governance/scope/id

PUT

Update a single IGA scope by id. This call expects the entire object to be provided and replaces the entire existing scope definition.

/governance/scope/id

PATCH

Update a single IGA scope by id. This call allows the caller to update specific properties of the scope only without providing the entire object.

/governance/scope/id

DELETE

Delete a single IGA scope by id.

/governance/scope/entity

GET

Get a list of available entities on which a condition can be defined.

/governance/scope/entity/object

GET

Get the available schema for defining a condition on a given object. For example, 'user' returns the attributes available for defining a scope for users in IGA.

Evolving APIs

The APIs referenced in this section are evolving, which means they can change or become deprecated at any time.

The current evolving APIs focus on entitlements. For more information, refer to Manage entitlements.

URI HTTP method Description

/governance/resource/id

GET

Get an entitlement by an ID.

/governance/resource/search

POST

Search for a list of entitlements that match a query.

/governance/resource/id/assignments/user

GET

Gets the users assigned to a specific entitlement.

Access grant

Access grants are one-to-one relationships between an end user and a resource.

For example, when you assign an end user to an entitlement, Identity Governance correlates the user to that entitlement. This one-to-one correlation is an entitlement grant. If an entitlement has 12 users associated, there are 12 entitlement grants.

For each entitlement grant, a confidence score can be assigned using Autonomous ID (Autonomous Identity).

With Autonomous Identity data exported, import the confidence scores into Identity Governance. The confidence scores display on line-items in a certification. This assists certifiers regarding which actions to take during a certification. For example, if the confidence score for an end user to have an entitlement is 90, then the certifier can have a high degree of certainty that the end user can have the entitlement.

The following table shows the endpoints relating to an entitlement grant’s glossary metadata:

Only create confidence scores for access grants from data generated from Autonomous Identity.

When importing the confidence scores from Autonomous Identity, use a script to iterate over the resource ID and account ID.
URI HTTP method Description

/governance/entitlementGrant/glossary

GET

Retrieve a single entitlement grant’s glossary metadata by account and entitlement ID.

/governance/entitlementGrant/glossary

POST

Create a single entitlement grant’s glossary metadata by account and entitlement ID.

/governance/entitlementGrant/glossary

PUT

Create or update a single entitlement grant’s glossary metadata by account and entitlement ID.

Request forms

Identity Governance enables administrators to create custom forms presented to users during request workflows.

URI HTTP method Description

/governance/requestForms

GET

Search request forms.

/governance/requestForms

POST

Create a request form.

/governance/requestForms/id

GET

Retrieve a request form by ID.

/governance/requestForms/id

PUT

Replace an existing request form by ID.

/governance/requestForms/id

PATCH

Update an existing request form by ID.

/governance/requestFormAssignments

GET

Search the request form assignments.

/governance/requestFormAssignments

POST

Assign and unassign a request form.

Segregation of duties

The Segregation of Duties (SoD) is an internal control process ensuring no single individual is granted privileges that could lead to a conflict of interest or fraud. Administrators can set this process using policies and policy rules to identify violations and run actions, such as create an exception, allow violation, remediate the violation and others.

For your convenience, you can view the entire API using a YAML file based on the OpenAPI specification.

To download the YAML file, click here.

Adjust the configurations of the file to match your specific details, such as your Advanced Identity Cloud tenant FQDN.
URI HTTP method Description

/governance/policy

GET

Search policies. The endpoint returns policies stored within the Identity Governance store, based on a set of query parameters.

/governance/policy

POST

Create a policy.

/governance/policy/search

POST

Search policy objects using a target search filter.

/governance/policy/{id}

GET

Get policy by ID. The endpoint returns the policy with the provided ID.

/governance/policy/{id}

PUT

Update an existing policy object.

/governance/policy/{id}

DELETE

Delete an existing policy object.

/governance/policy/{id}/scan

POST

Scan the given policy for violations and create violations if desired.

/governance/policy/{id}/rules

GET

Get policy rules associated with a policy ID.

/governance/policy/rule

GET

Query policy rules.

/governance/policy/rule

POST

Create a new policy rule.

/governance/policy/rule/search

POST

Search policy rules using a targeted search filter.

/governance/policy/rule/{id}

GET

Get policy rule by ID.

/governance/policy/rule/{id}

POST

Duplicate a given policy rule. The rule will be set as inactive by default.

/governance/policy/rule/{id}

PUT

Update an existing policy rule object.

/governance/policy/rule/{id}

DELETE

Delete an existing policy rule.

/governance/policy/rule/{id}/scan

POST

Scan the given policy for violations and create violations if desired.

/governance/policy/user/{id}/scan

POST

Run a scan for violations based on a given single user and return potential violations.

/governance/policy/scan

GET

Query policy scans.

/governance/policy/scan/search

POST

Search policy scan objects using a targeted search filter.

/governance/policy/scan/{id}

GET

Get policy scan by ID.

/governance/policy/scan/{id}

DELETE

Delete an existing policy scan.

/governance/user/violation

GET

Get violations the logged-in end user has access to.

/governance/violation

GET

Get the violation objects.

/governance/violation

POST

Creates a violation.

/governance/violation/allow

POST

Bulk API to close entire violations, allowing access to remain definitely.

/governance/violation/cancel-exception

POST

Bulk API to cancel exception on a group of violations, reverting the violations back to in-progress.

/governance/violation/comment

POST

Bulk API to allow actors to add a comment to the violations.

/governance/violation/exception

POST

Bulk API to allow access to remain for a defined period of time.

/governance/violation/reassign

POST

Bulk API to edit the actors and permissions on the violations.

/governance/violation/search

POST

Query the violation objects using a targeted search filter.

/governance/user/violation/search

POST

Search violations the logged-in user is associated with.

/governance/violation/{id}

GET

Query the contents of a single violation object.

/governance/violation/{id}

PUT

Updates a given violation.

/governance/violation/{id}

DELETE

Deletes a violation with a given ID.

/governance/violation/{id}/allow

POST

Close entire violation, allowing access to remain indefinitely.

/governance/violation/{id}/comment

POST

Add a comment to a violation object.

/governance/violation/{id}/remediate

POST

Complete a violation with an outcome of remediate and continue the workflow process to either the automated workflow or manual process for fulfilling the remediation.

/governance/violation/{id}/remediation/status/{status}

POST

Update the remediationStatus of a violation from in-progress to complete and finalize the violation when appropriate.

/governance/violation/{violationId}/phases

POST

Add a phase to a violation. A phase is a task that must be completed to move the violation forward, which depends on the task configuration, such as expiration, assignee, notifications, and others. For type=violation, the task allows users to select allow or remediate.

/governance/violation/{id}/phases/{phaseName}/allow

POST

Make a decision to allow access to remain. As an actor on a violation, allow the user to continue to violate the defined rule in perpetuity.

/governance/violation/{id}/phases/{phaseName}/cancel-exception

POST

Cancel an exception on a violation. As an actor on a violation, cancel an existing exception, reverting the violation back to in-progress.

/governance/violation/{id}/phases/{phaseName}/comment

POST

Add a comment to a violation object.

/governance/violation/{id}/phases/{phaseName}/exception

POST

Allow access to remain for a defined period of time. As an actor on a violation, grant an exception to the violating access.

/governance/violation/{id}/phases/{phaseName}/reassign

POST

As a violation actor, edit the actors and permissions on a violation task.

/governance/violation/{id}/phases/{phaseName}/remediate

POST

Make a decision to remediate access. As a violation actor, choose to remediate the access, kicking off the remediation workflow assigned to the violation.

/governance/violation/{id}/phases/{phaseName}/complete

POST

Mark a violation provisioning task as complete. As an actor on a manual provisioning task to handle the violation remediation, mark the action as completed.

/governance/violation/{id}/phases/{phaseName}/cancel

POST

Mark a violation provisioning task as canceled (i.e., not completed). As an actor on a manual provisioning task to handle the violation remediation, mark the action as canceled (not completed).

/governance/violation/remediationSchema

GET

Get a list of supported violation remediation schemas.

/governance/violation/remediationSchema

POST

Create a new violation remediation schema.

/governance/violation/remediationSchema/search

POST

Search the remediation schema.

/governance/violation/remediationSchema/{violationRemediationSchemaId}

GET

Get the violation remediation schema by ID.

/governance/violation/remediationSchema/{violationRemediationSchemaId}

PUT

Update the existing violation remediation schema.

/governance/violation/remediationSchema/{violationRemediationSchemaId}

DELETE

Delete a violation remediation schema.

/governance/violation/scan/{scanType}

POST

Check the active violation objects for certain criteria, such as reminder notifications, expiration, creation status, and others.
Copyright © 2010-2024 ForgeRock, all rights reserved.