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.

Learn more in the API reference documentation.

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.

Learn more in access requests.

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/{requestTypeId}

POST

Create request for the given request type.

/governance/requests/{requestId}

GET

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

/governance/requests/{requestId}

PUT

Replace the content of a request. The only properties that can be changed are properties that are defined in the request schema and not in the nonModifiableProperties.

/governance/requests/{requestId}

PATCH

Update the contents of a request. The only properties that can be updated are properties that are defined in the request schema and not in the nonModifiableProperties.

/governance/requests/{requestId}

POST

Perform various actions on a specific request, such as approve, reject, comment, cancel, update, or reassign. Each action may have different payloads depending on the information the caller needs to provide.

/governance/user/{userId}/requests

GET

Get requests for which the authenticated user has permissions to view. For additional search capabilities, use the POST /governance/user/{userId}/requests?_action=search API.

/governance/user/{userId}/requests

POST

Get requests for which the authenticated user has permissions to view. The targetFilter property in the API payload can be used to filter the requests based on the desired criteria.

/governance/user/{userId}/approvals

POST

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

Account

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

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 all account objects across all applications that have been onboarded as part of any application. Additional filter criteria can be provided to allow searching by application, user, or glossary data.

/governance/account/{accountId}

GET

Retrieve by details of a single account object using its unique identifier.

/governance/account/{accountId}/glossary

GET

Retrieve the glossary specific details of a single account object using its unique identifier.

/governance/account/{accountId}/glossary

POST

Create glossary entry for a single account object using its unique identifier.

/governance/account/{accountId}/glossary

PUT

Create or update a glossary entry for a single account object using its unique identifier.

Audit

Endpoints associated with IDM’s audit functionality.

To use the iga/governance/workflow and iga/governance/audit endpoints, your authorization token must have the following scope:

fr:idc:analytics.*

This is a temporary requirement and will be removed in a future release.
URI HTTP method Description

/governance/audit

GET

Get audit reports.

/governance/user/{userId}/audit

GET

Get the audit reports for a given user.

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.

You can find more information in the Manage governance glossary.

URI HTTP method Description

/governance/catalog

GET

Get a list of items from the Identity Governance access catalog. Each entry represents a single type of requestable access that can be added to a request. The current supported types of access that are requestable are application, entitlement, and role.

/governance/catalog

POST

Get a list of items from the Identity Governance access catalog using additional filter criteria. Each entry represents a single type of requestable access that can be added to a request. The current supported types of access that are requestable are application, entitlement, and role.

/governance/search/schema

GET

Retrieve all currently configured properties eligible to be used for search or sort when searching against the catalog API. Each property includes some additional metadata about the property, such as whether it is multivalued or not and its datatype.

/governance/search/schema/{objectType}

GET

Retrieve all currently configured properties eligible to be used for search or sort for a single object when searching against the catalog API. For example, you can use the endpoint to search for all specific entitlement properties. Each property includes some additional metadata about the property, such as whether it is multivalued or not and its datatype.

Certification

URI HTTP method Description

/governance/certification/template

GET

Query existing certification templates.

/governance/certification/template

POST

Create a new certification template.

/governance/certification/template/{id}/duplicate

POST

Duplicate an existing certification template.

/governance/certification/template/{id}

PUT

Update a single certification template.

/governance/certification/template/{id}

DELETE

Delete a single certification template.

/governance/certification/get-filter-schema

POST

Get the available schema on which to filter certification templates.

/governance/certification/admin/certification

GET

Query existing certification campaign instances.

/governance/certification/admin/certification/{certId}

GET

Read a single certification campaign.

/governance/certification/admin/certification/{certId}/tasks

GET

Get the actors (certifiers) tasks view for a certification.

/governance/certification/admin/certification/{certId}/update-deadline

POST

Update a certification’s deadline.

/governance/certification/admin/certification/{certId}/cancel

POST

Cancel a certification campaign.

/governance/certification/certification/items

GET

Query the review items (tasks) that are assigned to you.

/governance/certification/certification/{certId}/items

GET

Query line items of the certification campaign instance.

/governance/certification/certification/{certId}/items/search

POST

Query line items of the certification campaign instance.

/governance/certification/certification/{certId}/items/{action}

POST

Take action on line items.

/governance/certification/certification/{certId}/items/{lineItemId}/{action}

POST

Take action on a single line item.

Config

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

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 all Identity Governance 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 configuration settings for a given category (for example, iga_access_request).

/commons/config/{key}

PUT

Update Identity Governance configuration settings for a given category (for example, iga_access_request).

Event

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.

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 event 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.

Job

Endpoint to trigger an Identity Governance’s job process.

URI HTTP method Description

/governance/jobs/{id}

POST

Manualy triggers one of IGA’s job processes.

Request form

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

Get 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.

Request type

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

/governance/requestTypes

GET

Get a list of supported request types.

/governance/requestsTypes

POST

Create a new custom request type.

/governance/requestsTypes/{requestTypeId}

GET

Get the request type by ID.

/governance/requestsTypes/{requestTypeId}

PUT

Replace an existing request type.

/governance/requestsTypes/{requestTypeId}

PATCH

Update a request type.

/governance/requestsTypes/{requestTypeId}

DELETE

Delete a request 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.

URI HTTP method Description

/governance/user/{userId}/applications

POST

Provision or de-provision applications for an end user.

/governance/user/{userId}/roles

POST

Provision or de-provision roles for an end user.

/governance/user/{userId}/entitlements

POST

Provision or de-provision entitlements for an end user.

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.

Segregation of Duty

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 configure SoD using policies and policy rules that let them identify violations and run actions, such as create an exception, allow or remediate the violation, and others.

You can view the entire API using a YAML file based on the OpenAPI specification.

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 new policy object within Identity Governance.

/governance/policy/search

POST

Query policy objects using a targeted 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 within Identity Governance.

/governance/policy/{id}

DELETE

Delete an existing policy object within Identity Governance.

/governance/policy/{id}/scan

POST

Run a scan on all given rules of a policy 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 based on a set of query parameters.

/governance/policy/rule

POST

Create a new policy rule object within Identity Governance.

/governance/policy/rule/search

POST

Query the policy rule objects 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

Run a scan the given policy for violations and create violations if desired.

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

POST

Run a scan on a given user rule and return potential violations.

/governance/policy/scan

GET

Query policy scans with the Identity Governance store based on a set of query parameters.

/governance/policy/scan/search

POST

Query 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 object within Identity Governance.

/governance/user/violation

GET

Query the signed-in user’s violation objects.

/governance/violation

GET

Query the violation objects.

/governance/violation

POST

Creates a violation with the given body.

/governance/violation/allow

POST

Once a phase (or phases) have chosen to allow a violation, close and complete the violations with the outcome of allow.

/governance/violation/cancel-exception

POST

As a user who can take action on violations, cancel existing exceptions, reverting the violations back to in-progress.

/governance/violation/comment

POST

As a user who can take action on violations, add a comment to the violation objects.

/governance/violation/exception

POST

As a user who can take action on violations, grant an exception to the violating access.

/governance/violation/reassign

POST

As a user who can take action on violations, edit the list of active actors on the violation tasks.

/governance/violation/search

POST

Query the violation objects using a targeted search filter.

/governance/user/violation/search

POST

Query the signed-in user’s violation object using a targeted search filter.

/governance/violation/{id}

GET

Query the contents of a single violation object.

/governance/violation/{id}

PUT

Updates a given violation with the given body.

/governance/violation/{id}

DELETE

Deletes a violation with a given ID.

/governance/violation/{id}/allow

POST

Once a phase (or phases) have chosen to allow a violation, close and complete the violation with an outcome of allow.

/governance/violation/#{id}/comment

POST

As an actor on a violation, add a comment to a violation object.

/governance/violation/{id}/remediate

POST

Once a phase (or phases) have chosen to remediate a violation, complete the violation with an outcome of remediate and continue the workflow on to either the automated or manual process for fulfilling the remediation.

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

POST

For violations with an outcome of remediate, allow the remediationStatus key to be updated. For example, 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

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

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

As an actor on a violation, grant an exception to the violating access.

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

POST

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

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

POST

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

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

POST

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

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

Task

Endpoints for fulfillment tasks.

URI HTTP method Description

/governance/user/{userId}/tasks

GET

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

/governance/user/{userId}/tasks

POST

Get the tasks for which the authenticated user has permissions to view. The targetFilter property in the payload can be used to filter requests based on the desired criteria.

User

Endpoint for a user’s grants and recommendations.

URI HTTP method Description

/governance/user/{userId}/grants

GET

Get the grants a user currently has.

/governance/user/{userId}/recommendations

GET

Get the access recommendations for a given user.

Workflow

To use the iga/governance/workflow and iga/governance/audit endpoints, your authorization token must have the following scope:

fr:idc:analytics.*

This is a temporary requirement and will be removed in a future release.
URI HTTP method Description

/governance/workflow

GET

Get the workflow definitions.

/governance/workflow

Post

Create and/or publish workflow definitions.

/governance/worflow/{id}/{status}

GET

Get the workflow definition.

/governance/worflow/{id}/{status}

DELETE

Delete the workflow definition. If the status is published, it will try to delete the workfow model and process the definition in IDM.

/governance/worflow/{id}

PUT

Update or publish the workflow definition.

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 all entitlements that match the target filter.

/governance/resource/{id}/assignments/user

GET

Gets the users assigned to a specific entitlement.