Verify Governance REST APIs
The Verify Governance platform provides a REST API set for managing the main elements of the data model (users, entitlements, permissions, rights, accounts, and also authorization work-flows and SOD attributes.
The API implements the Simple Cloud Identity Management (SCIM) standard (version 2.0), with custom schema extensions. This implementation enables developers to access and manage identity resources directly by developing client applications that can be invoked from anywhere within the network.
Prerequisites
Before you proceed, you must be familiar with the following technologies:
- RESTful API
- JSON (JavaScript Object Notation)
- SCIM specification (RFC7643, RFC7644)
You must also be familiar with the Verify Governance data model.
Restrictions
There is no support for SCIM query filter expressions with or operator.
There is no support for using parenthesis or brackets for building query filters.
In a filter string, each attribute must be preceded by the Universal Resource Name (URN).
For example:
urn:ietf:params:scim:schemas:core:2.0:User:name.givenName co \"James\").
Currently, the available operators are:
and- Boolean operator
eq- Operator for comparing if a field of a schema is equal to another entity.
co- Operator for checking whether a field of a schema is contained into another entity.
sw- Operator for checking whether a string starts with a preset string.
ew- Operator for checking whether a string ends with a preset string.
In the current release, some SCIM operations are not supported:
PATCH- Not applicable.
BULK- Not applicable.
Some SCIM standard attributes are not mapped in Verify Governance data model.
You can find this information looking at the Resource Schema.
In SCIM query, the paging mechanism that is adopted is different from the SCIM specification.
The paging is page-based, where the
startPage field of SCIM Search Request indicates
the page target and the count field specifies the
number of elements in that page.
Supported REST APIs
The following table lists the supported Verify Governance REST APIs.
| Category | API Name | Resource | Endpoint | Operation | Description |
|---|---|---|---|---|---|
| Access Certifier (AC) API methods | Act on Account by Campaign Note: Available with Fix Pack 1.
|
Account | /igi/v2/ac/campaigns/{campaign_id}/accounts/assignmentsreviews | POST | Acts on one or more accounts to work by campaign. |
| Find Account by Campaign Note: Available with Fix Pack 1.
|
Account | /igi/v2/ac/campaigns/{campaign_id}/accounts/assignmentsreviews.search | POST | Finds one or more accounts to work on by campaign. | |
| Find Account by Reviewer by Campaign Note: Available with Fix Pack
1.
|
Account | /igi/v2/ac/campaigns/{campaign_id}/supervisor/reviewers/{reviewer_id}/accounts/assignmentsreviews/.search | POST | Shows to supervisor the assignments for one or more accounts that a selected reviewer is reviewing in a selected campaign. | |
| Find Supervisor to Escalate Account Note: Available with Fix Pack
1.
|
Account | /igi/v2/ac/campaigns/{campaign_id}/accounts/{assignmentid_towork}/escalate/supervisors | GET | Finds a supervisor to whom to escalate review. | |
| Find User to Redirect Account Note: Available with Fix Pack
1.
|
Account | /igi/v2/ac/campaigns/{campaign_id}/accounts/{assignmentid_towork}/redirectors/.search | POST | Finds one or more users to whom to redirect an account for review. | |
| Get Statistics about Account Assignments Note: Available with Fix Pack
1.
|
Account | /igi/v2/ac/campaigns/{campaign_id}/stats/accounts/assignmentsreviews | GET | Gets statistics about the account assignments that were reviewed in a campaign. | |
| Find Campaign | Campaigns | /igi/v2/ac/campaigns/.search | POST | Finds one or more campaigns in visibility to the user. | |
| Stats Campaigns | Campaigns | /igi/v2/ac/campaigns/stats | GET | Returns the number of campaigns of each type for which the logged in user is reviewer or supervisor. | |
| Find Reviewers | Campaigns-Supervisor | /igi/v2/ac/campaigns/{campaign_id}/supervisor/reviewers/.search | POST | Finds one or more reviewers involved in a campaign. | |
| Act on Assignment by Campaign | User Assignment | /igi/v2/ac/campaigns/{campaign_id}/assignmentsreviews | POST | Acts on one or more assignments to work by campaign. | |
| Find Assignment Reviewer by Campaign | User Assignment | /igi/v2/ac/campaigns/{campaign_id}/assignmentsreviews | GET | Finds the reviewer of an assignment to work by campaign. | |
| Find Entitlement by Campaign | User Assignment | /igi/v2/ac/campaigns/{campaign_id}/assignmentsreviews/.search | POST | Finds one or more entitlements to work of a user by campaign. | |
| Find Supervisor to Escalate User Assignment | User Assignment | /v2/ac/campaigns/{campaign_id}/assignmentsreviews/{assignmentid_towork}/escalate/supervisors | GET | For a given campaign, finds supervisors for escalation. | |
| Find User by Campaign | User Assignment | /igi/v2/ac/campaigns/{campaign_id}/users | GET | Finds one or more users to work by campaign. | |
| Find User to Redirect User Assignment | User Assignment | /igi/v2/ac/campaigns/{campaign_id}/assignmentsreviews/{assignmentid_towork}/redirectors/.search | POST | Finds one or more users to redirect an assignment to work. | |
| Get Statistics about User Assignments | User Assignment | /v2/ac/campaigns/{campaign_id}/stats/assignmentsreviews | GET | Gets statistics about the assignments that were reviewed in a given campaign. | |
| User View by Campaign | User Assignment | /igi/v2/ac/campaigns/{campaign_id}/users/.search | POST | Shows the users (User View) that are listed for review in a selected campaign. | |
| Entitlement View by Reviewer | User Assignment-Supervisor | /igi/v2/ac/campaigns/{campaign_id}/supervisor/reviewers/{reviewer_id}/assignmentsreviews/.search | POST | Shows to supervisor the assignments for one or more users (Entitlement View) that a selected reviewer is reviewing in a selected campaign. | |
| User View by Reviewer | User Assignment-Supervisor | /igi/v2/ac/campaigns/{campaign_id}/supervisor/reviewers/{reviewer_id}/users/.search | POST | Shows to supervisor the users (User View) that a selected reviewer is reviewing in a selected campaign. | |
| Act on Job Unit by Campaign | Organizational Unit | /igi/v2/ac/campaigns/{campaign_id}/organizationalunits/assignmentsreviews | POST | Acts on (approve/revoke/sign-off/redirect/note) one or more OU assignments to review by campaign. | |
| Find Job Unit by Campaign | Organizational Unit | /igi/v2/ac/campaigns/{campaign_id}/organizationalunits/assignmentsreviews.search | POST | Finds all the OU assignments to review (filtered by OU) by campaign. | |
| Find Organizational Unit by Campaign | Organizational Unit | /igi/v2/ac/campaigns/{campaign_id}/organizationalunits/.search | POST | Finds all the organizational units to review by campaign. | |
| Find Supervisor to Escalate OU | Organizational Unit | /igi/v2/ac/campaigns/{campaign_id}/organizationalunits/{assignmentid_towork}/escalate/supervisors | GET | For a given campaign, finds supervisors for escalation. | |
| Find User to Redirect OU | Organizational Unit | /igi/v2/ac/campaigns/{campaign_id}/organizationalunits/{assignmentid_towork}/redirectors/.search | POST | Finds one or more users to redirect an organizational unit to review. | |
| Get Statistics about OU Assignments | Organizational Unit | /igi/v2/ac/campaigns/{campaign_id}/stats/organizationalunits/assignmentsreviews | GET | Gets statistics about the assignments that were reviewed in a given campaign. | |
| Inspect OU by Reviewer | Organizational Unit-Supervisor | /igi/v2/ac/campaigns/{campaign_id}/supervisor/reviewers/{reviewer_id}/organizationalunits/assignmentsreviews/.search | POST | Shows to supervisor the assignments for one or more Organizational Units (Inspect OU View) that a selected reviewer is reviewing in a selected campaign. | |
| Org. Unit View by Reviewer | Organizational Unit-Supervisor | /igi/v2/ac/campaigns/{campaign_id}/supervisor/reviewers/{reviewer_id}/organizationalunits/.search | POST | Shows to supervisor the Organizational Units (Org. Unit View) that a selected reviewer is reviewing in a selected campaign. | |
| Access Governance Core (AGC) API methods | Add User | Users | /igi/v2/agc/users | POST | Creates the object User that represents the digital identity of a common user of an organization. |
| Delete User | Users | /igi/v2/agc/users/{userId} | DELETE | Deletes the object User. | |
| Find User | Users | /igi/v2/agc/users/.search | POST | Finds user by a SCIM search request. | |
| Info Application User | Users | /igi/v2/agc/users/info/applications/.search | POST | Returns application information for the logged in user. | |
| Info User | Users | /igi/v2/agc/users/info | GET | Returns personal information of the logged in user. | |
| Move OU User | Users | /igi/v2/agc/users/{userId}/group | GET | Moves a user from an OU to another, and assigns the roles based on the parameter set. | |
| Find User Advanced | Users | /igi/v2/agc/users/advanced/.search | POST | Finds users allowing also to filter by external attributes. | |
| Replace User | Users | /igi/v2/agc/users/{userId} | PUT | Updates user information. | |
| Find User by ID | Users | /igi/v2/agc/users/{userId} | GET | Finds a user through the User ID. | |
| Add User Account | Users - Accounts | /igi/v2/agc/users/accounts | POST | Adds an Account object to the data model. | |
| Change Password Account | Users - Accounts | /igi/v2/agc/users/accounts/{account_id} | PATCH | Changes the password of a specific account. The password field represents the Verify Governance current password for the account. | |
| Change Password Accounts | Users - Accounts | /igi/v2/agc/users/accounts/password | POST | Changes the password of a set of accounts. | |
| Change Password | Users - Accounts | /igi/v2/agc/users/accounts/{account_id}/password | POST | Changes the password of a specific account. The IGIPwd field represents
the IGI current password for that account. Attention: If the
rest.api.visibility parameter is set to
true, an end user can
change passwords only for owned accounts. Also, to avoid password enumeration, the account is
blocked based on the password management Maximum number of password retries field.
This is the default.If the parameter is set to An
See Changing the user visibility of selected REST APIs for details. Important: To be
able to use the IBM Security Verify Request mobile app, or to
integrate with the ServiceNow platform,
the rest.api.visibility parameter must be set to
false. |
|
| Check Password Accounts | Users - Accounts | /igi/v2/agc/users/accounts/password/check | POST | Checks if the specified password complies with the password policies of a set of accounts. | |
| Check Password For New Account | Users - Accounts | /igi/v2/agc/accountcfg/{accountcfg_id}/password/check | POST | Checks if the password specified for a new account complies with the password policies of a specific account (see Get Password Policy). | |
| Check Password | Users - Accounts | /igi/v2/agc/users/accounts/{account_id}/password/check | POST | Checks if the password specified complies with the password policies of a specific account (see Get Password Policy). | |
| Delete User Account | Users - Accounts | /igi/v2/agc/users/accounts/{accountId} | DELETE | Deletes an account. | |
| Find User Account | Users - Accounts | /igi/v2/agc/users/{user-id}/accounts/.search | POST | Finds one or more Account objects that are associated to a user
through a SCIM search request. Attention: If the
rest.api.visibility parameter is set to
true, an end user can
find information only about owned accounts. This is the default.If the parameter is set to
An See Changing the user visibility of selected REST APIs for details. Important: To be able to use the IBM Security Verify Request mobile app, or to integrate with the ServiceNow platform, the
rest.api.visibility parameter must be set to
false. |
|
| Change User Account Status | Users - Accounts | /igi/v2/agc/users/accounts/{account_id}/status | PUT | Changes the user account status: disable or enable the account according to specific values. | |
| Replace User Account | Users - Accounts | /igi/v2/agc/users/accounts/{accountId} | PUT | Replaces an account. | |
| Get Account Target Attributes | Users - Accounts | /igi/v2/agc/users/accounts/{accountId}/targetattributes | GET | Gets the target attributes of an account. | |
| Validate Password | Users - Accounts | /igi/v2/agc/users/accounts/PasswordValidateRequests | POST | Validates if a specified password complies with the password policies of a specific account (see Get Password Policy). | |
| Add Account Configuration | Account Configurations | /igi/v2/agc/accountcfg | POST | Adds an Account Configuration object to the data model. | |
| Delete Account Configuration | Account Configurations | /igi/v2/agc/accountcfg/{cfgId} | DELETE | Deletes an Account Configuration. | |
| Find Account Configurations | Account Configurations | /igi/v2/agc/accountcfg/.search | POST | Finds account configurations in the Verify Governance database. | |
| Find Attribute Keys by Account Configuration | Account Configurations | /igi/v2/agc/accountcfg/{cfgId}/attributekeys | GET | Finds attribute keys by account configuration. | |
| Get Password Policy | Account Configurations | /igi/v2/agc/accountcfg/password/policy | GET | Gets the password policy that is shared by a set of account configurations. Attention: If the rest.api.visibility parameter is set to
true, an end user can find information only for the password policies that are
related to account configurations of owned accounts. This is the default.If the parameter is set
to An See Changing the user visibility of selected REST APIs for details. Important: To be able to use the IBM Security Verify Request mobile app, or to integrate with the ServiceNow platform, the
rest.api.visibility parameter must be set to
false. |
|
| Replace Account Configuration | Account Configurations | /igi/v2/agc/accountcfg/{cfgId} | PUT | Replaces an account configuration. | |
| Find Label Localizations by Attribute Key by Account Configuration | Account Configurations | /igi/v2/agc/accountcfg/{cfgId}/attributekeys/{attrkeyId}/localizations | GET | Finds the label for one or more localizations by Attribute Key by Account Configuration | |
| Add Application | Applications | /igi/v2/agc/applications | POST | Adds an Application object to the data model. | |
| Delete Application | Applications | /igi/v2/agc/applications/{appId} | DELETE | Deletes an Application. | |
| Find Application | Applications | /igi/v2/agc/applications/.search | POST | Finds an Application through a SCIM search request. | |
| Replace Application | Applications | /igi/v2/agc/applications/{appId} | PUT | Replaces an Application. | |
| Find User Entitlement | Entitlement | /igi/v2/agc/users/{userId}/entitlement/.search | POST | Finds the entitlements of the user through a SCIM search request. | |
| Find Available User Entitlement | Entitlements | /igi/v2/agc/users/{userId}/entitlement/available/.search | POST | Finds all the available entitlements for a user through a SCIM search request. | |
| Find User Rights | Rights | /igi/v2/agc/users/{userId}/entitlement/rights | GET | Finds the list of rights that are associated to an entitlement. | |
| Add User Entitlement | Entitlements | /igi/v2/agc/users/{userId}/entitlement | POST | Adds an entitlement to a user. | |
| Remove User Entitlement | Entitlements | /igi/v2/agc/users/{userId}/entitlement/{entId} | DELETE | Removes an entitlement that is associated to a user. | |
| Add Entitlement | Entitlements | /igi/v2/agc/entitlements | POST | Adds an object Entitlement to the data model. | |
| Find Entitlement | Entitlements | /igi/v2/agc/entitlements/.search | POST | Finds entitlements through a SCIM search request. | |
| Delete Entitlement | Entitlements | /igi/v2/agc/entitlements/{entId} | DELETE | Deletes one or more objects of type Entitlement. | |
| Replace Entitlement | Entitlements | /igi/v2/agc/entitlements/{entitlementId} | PUT | Updates an entitlement. | |
| Add Entitlement Child | Entitlements | /igi/v2/agc/entitlements/{entld}/entitlement | POST | Adds one or more entitlements to a Business role or IT role. | |
| Remove Entitlement Child | Entitlements | /igi/v2/agc/entitlements/{entld}/entitlement | DELETE | Removes one or more entitlements from a Business role or IT role. | |
| Find Entitlement Child | Entitlements | /igi/v2/agc/entitlements/{entld}/entitlement/.search | POST | Finds entitlement's child through a SCIM search request. | |
| Add Entitlement in Group | Hierarchies-Groups | /igi/v2/agc/groups/{group_id}/entitlement | POST | Adds one or more entitlements to a group. | |
| Add Group | Hierarchies-Groups | igi/v2/agc/hierarchies/{hierarchy_id}/groups/{groupParentId} | POST | Adds an object Group to the data model. | |
| Delete Group | Hierarchies-Groups | igi/v2/agc/hierarchies/{hierarchy_id}/groups/{groupId} | DELETE | Deletes an object Group. | |
| Find Entitlement in Group | Hierarchies-Groups | igi/v2/agc/groups/{group_id}/entitlement/.search | POST | Finds entitlements in a group by a SCIM search request. | |
| Find Group | Hierarchies-Groups | /igi/v2/agc/hierarchies/{hierarchy_id}/groups/.search | POST | Specifies the group hierarchy to find. If you do not specify a value, the default value is set to 1, indicating the default group ORGANIZATIONAL_UNIT. | |
| Remove Entitlement from Group | Hierarchies-Groups | /igi/v2/agc/groups/{group_id}/entitlement | DELETE | Removes one or more entitlements from a group. | |
| Replace Group | Hierarchies-Groups | /igi/v2/agc/hierarchies/{hierarchy_id}/groups/{groupId} | PUT | Updates the details of a group. | |
| Add Group Hierarchy | Hierarchies | igi/v2/agc/hierarchies | POST | Adds a group hierarchy. | |
| Build Group Hierarchy | Hierarchies | /igi/v2/agc/hierarchies/build/{hierarchy_id} | GET | Builds a group hierarchy. | |
| Find Group Hierarchy | Hierarchies | igi/v2/agc/hierarchies/.search | POST | Finds a group hierarchy through a SCIM search request. | |
| Remove Group Hierarchy | Hierarchies | /igi/v2/agc/hierarchies/{hierarchy_id} | DELETE | Removes a group hierarchy. | |
| Replace Group Hierarchy | Hierarchies | /igi/v2/agc/hierarchies/{hierarchy_id} | PUT | Updates the details of a group hierarchy. | |
| Get Lookup Values by Lookup | Lookup | /igi/v2/agc/lookup/{name_lookup} | GET | Gets the lookup values by lookup. | |
| Add Target | Targets | /igi/v2/agc/targets | POST | Adds a Target object to the data model. | |
| Delete Target | Targets | /igi/v2/agc/targets/{targetId} | DELETE | Deletes a Target. | |
| Find Target | Targets | /igi/v2/agc/targets/.search | POST | Finds a Target through a SCIM search request. | |
| Replace Target | Targets | /igi/v2/agc/targets/{targetId} | PUT | Replaces a Target. | |
| Access Request Management (ARM) API methods | Find Workflow | Workflows | /igi/v2/arm/workflows/.search | POST | Finds the workflow IDs available for the logged user. |
| Find User by Workflow | Requests-Access | /igi/v2/arm/{workflowId}/users/.search | POST | Finds users according to a variable set of parameters. | |
| Find User Entitlement by Workflow | Requests-Access | /igi/v2/arm/{workflowId}/users/{user_id}/entitlements/.search | POST | Finds the entitlements that are assigned to a user according to the workflow associated to a user. | |
| Generate User Role Request | Requests-Access | /igi/v2/arm/{workflowId}/requests/user/entitlements | POST | Generates request for user role assignment (add roles, remove roles, update roles). | |
| Find Request | Requests | /igi/v2/arm/requests | GET | Gets one or more requests by type. | |
| Find Request to Work | Requests | /igi/v2/arm/{workflowId}/requests/.search | POST | Finds the IDs of the requests that are related to the next activities to be processed. | |
| Find Request Detail | Requests | /igi/v2/arm/requests/{request_id} | GET | Gets the details of a request. Attention: If
the rest.api.visibility parameter is set to
true, an end user
can find details only for the requests of which is applicant. This is the default.If the
parameter is set to An See Changing the user visibility of selected REST APIs for details. Important: To be able to use the IBM Security Verify Request mobile app, or to integrate with the ServiceNow platform, the
rest.api.visibility parameter must be set to
false. |
|
| Auth or Exe Request | Requests | /igi/v2/arm/requests/{request_id} | POST | If the request is of type AUTH, approves or rejects a generated request. If the request is of type EXE, after the approving of the request, an operator makes the needed updates on the target system. Thus, flag the request as "completed". | |
| Requests Summary | Requests | /igi/v2/arm/{workflowId}/requests/.search | POST | Gets a summary of all the requests that were submitted by the logged user. It is important to pass a report workflow. | |
| Find User Admin Roles by workflow | Delegation | /igi/v2/arm/{workflowId}/users/{user_id}/adminentitlements/.search | POST | Finds the admin roles that are assigned to a user, according to the workflow associated to a user through a SCIM search request. | |
| Find User Admin Roles delegated by workflow | Delegation | /igi/v2/arm/{workflowId}/users/{userid_beneficiary}/delegated/users/{userid_delegator}/adminentitlements/.search | POST | Finds the admin roles, that are delegated from one user to another, according to the workflow associated to a user through a SCIM search request. | |
| Find User Delegator by workflow | Delegation | /igi/v2/arm/{workflowId}/users/delegators/.search | POST | Finds delegating users, according to a variable set of parameters through a SCIM search request. | |
| Generate Delegation Request | Delegation | /igi/v2/arm/{workflowId}/requests/user/delegation | POST | Generates a request for user role delegation (add roles, remove roles, update roles). | |
| SCIM API methods | Resource Schema | Resource Schema | /igi/v2/schemas/{resourceSchema} | GET | Gets resource schema, according to the Universal Resource Name (URN). |
| Service Provider Configuration | Service Provider Configuration | /igi/v2/serviceproviderconfig | GET | Gets the list of SCIM operations supported, such as filtering, bulk, change password, authentication, and patch. Each operation can be supported or not. | |
| Resource Discovery | Resource Discovery | /igi/v2/resourcetype | GET | Gets list of resources that are provided by server. | |
| Security API methods | Act As Delegate for | Security Token | /igi/v2/security/login/actas/{represented} | GET | Acts As Delegate to Verify Governance system and obtains token needed to call next methods |
| Find Delegator User Admin Entitlement | Security Token | /igi/v2/security/users/adminentitlements/delegated/.search | POST | Finds all the users that have delegated almost an admin entitlement to logged user. | |
| Login | Security Token | /igi/v2/security/login | GET | Logs in to Verify Governance system and obtains the token that is needed to call next methods. | |
| Logout | Security Token | /igi/v2/security/logout | GET | Invalidates any Verify Governance token, provided to the API as the bearer token. These tokens are received
by the clients through the login API. Once a token is invalidated, it can no longer
be used for authenticating other API calls. The restart of the Verify Governance server will invalidate
any\all tokens that were issued until then. |
|
| Refresh Token | Security Token | /igi/v2/security/refresh | GET | Refresh token. Token expires after N minutes. The value N can be configured through the Virtual Appliance setting. | |
| Return to Self | Security Token | /igi/v2/security/login/actas | GET | Returns to Self (after an Act As action) to Verify Governance system and obtains token needed to call next methods | |
| Separation of Duties API | Check User | Risk | /igi/v2/arc/risks/users/{user_id} | POST | Checks the risks that are associated to a user. |
| Check User Full | Risk | /igi/v2/arc/risks/users/{user_id}/full | POST | Checks the full SoD risks that are associated to a user. |
Procedure for enabling HTTPS communication
Only HTTPS communication is supported.
See Managing certificates to enable secure communication.
API documentation
To access the REST APIs documentation:
-
For Version 10.0.1, download the ISVG-REST-API_10_0_1.zip file from https://www.ibm.com/support/pages/node/6407700 to your computer.
- Extract the files from ISVG-REST-API_10_0_1.zip into a folder.
- Open the index.html file in your web browser to display the REST API documentation.