REST API reference

Edit online

Detailed REST API documentation for the IBM Verify Identity Governance - Container in Swagger format.

Overview

The REST APIs for the IBM Verify Identity Governance - Container version 11.0.0 are available here in the Swagger format.

Note: For information about Access Assignment Batch APIs, see this topic.
You can also access these REST APIs from the IBM Verify Identity Governance - Container product user interface. Perform the following steps:
  1. Open the following URL in your web browser: https://{IP_ADDRESS}:{PORT_NUMBER}/openapi/ui/#/

    Here:

    IP_ADDRESS: Provide the IP address of your Kubernetes environment
    PORT_NUMBER: Provide the port number for IBM Verify Identity Governance - Container

  2. An index page appears with the list of REST APIs available for the IBM Verify Identity Governance - Container.

Invoking the REST APIs

This section describes how to invoke the REST APIs available for IBM Verify Identity Governance - Container.

There are three categories of REST APIs available and the way you invoke the APIs differs for each category.
Unprotected APIs

These APIs can be accessed with any authentication. You do not need to pass any additional header or cookies to invoke these.

For Example: GET “itim/rest/password/configuration” API returns the Password configuration for Identity Manager.

Protected APIs used for resource search/retrieval (GET)

The user needs to be authenticated and authorized to perform the operation. The request should contain LtpaToken2 cookie for the server to retrieve and validate the authentication information.

For Example: GET “/itim/rest/systemusers/me” API is used to get information about a user who is logged in to the Identity Manager system account.

Protected APIs used for resource creation/modification/deletion (PUT, POST, DELETE)

The user needs to be authenticated and authorized to perform the operation. The request should contain LtpaToken2 cookie for the server to retrieve and validate the authentication information. In addition to this cookie, a CSRFToken header and csrfToken cookie needs to be passed too.

For Example: POST “/itim/rest/people” API is used to create a new person with the given attributes.

Next, we will see the steps to retrieve LtpaToken2 cookie and CSRF token:

Retrieving the LtpaToken2 cookie and CSRF token
Perform the following steps.
  1. Get LtpaToken2 Cookie.
    Invoke following REST API to GET LtpaToken2 Cookie
    
POST /itim/j_security_check
Headers:
Content-Type: application/x-www-form-urlencoded
Body:
j_username: <username>
j_password: <password>
Response:
200 OK

    Response Cookies: LtpaToken2

  2. Retrieve CSRFToken Header and csrfToken Cookie.
    Invoke following REST API to retrieve CSRFToken header and csrfToken cookie:
    
GET /itim/rest/systemusers/me
Headers:
Cookie: <LtpaToken2 Cookie>
Response:
200 OK

    Response: 200 OK

    Response Headers: CSRFToken: <CSRF Token value>

    Response Cookies: csrfToken: <encoded CSRF Token cookie>

  3. Invoking PUT/POST/DELETE REST APIs
    Any PUT, POST, or DELETE API request should contain the following:
    • The request header must contain the CSRFToken that the authorized user received in the response header of “/itim/rest/systemusers/me” API.
    • Request cookies must contain LtpaToken2 cookie.
    • Request cookies must contain csrfToken cookie that is generated by invoking “/itim/rest/systemusers/me” API.

REST APIs for IM - Software Stack or IM - VA vs. IBM Verify Identity Governance - Container REST APIs

You should note a significant difference between REST APIs for Identity Manager - Software Stack or Identity Manager - Virtual Appliance and the REST APIs for IBM Verify Identity Governance - Container.

For IM-SS or IM-VA, the REST APIs use application server session for storing some data. Hence, there is a need to retrieve and pass JSESSIONID cookie for every request.

The IBM Verify Identity Governance - Container does not use JSESSIONID cookie for invoking REST APIs. However, due to this change, one needs to pass the csrfToken cookie for PUT, POST, and DELETE requests.

This difference must be taken into consideration if you are planning to migrate from SS or VA to IBM Verify Identity Governance - Container. You might have to modify your custom application.