NAV Navbar
shell

Identity Manager API documentation

Welcome to the VMware Identity Manager API documentation. We will be providing documentation to the most used Identity Manager API endpoints, along with examples, and detailed description.

We have language bindings in Shell and Python. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Feel free to reference Identity Manager Documentation portal for more information about Identity Manager SaaS and on-premises offerings.

Authentication

In order to start querying Identity Manager APIs, you need to obtain access token. To do that, you need to perform the following steps:

  1. Regest API access to obtain Client Secret
  2. Obtain Access Token
  3. Refresh Access Token when it expires

Let's look into these steps in detail.

Register API access

Before accessing the API you need to have a valid API access token. In order to obtain the access token, you first need to create a service client in the Identity Manager.

Token

As a result you will get the Client Secret that you can use to obtain the access token.

Example of client secret - fFjs8tGiloQD5ze4pL42EV6s0mufGrOG

Obtain Access Token

Once you have Client Secret, you can generate access token. Access token will then let you query various IDM API endpoints.

HTTP request

To request access token:

curl –X POST <your tenant name here> \
-H 'authorization: Basic Y3VybDpmRmpzOHRHaWxvUUQ1emU0cEw0MkVWNnMwbXVmR3JPRw==' \
-H 'content-type:application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'

IDM will return the following as a response:

{
    "access_token":"<your token here>",
    "token_type":"Bearer",
    "expires_in":10799,
    "refresh_token":"<your token here>",
    "scope":"admin"
}

POST https://[tenant location]/SAAS/auth/oauthtoken

Input parameters

Parameter Required Description
tenant location Yes (URL) Hostname of your tenant
grant_type=client_credentials Yes (Body) Required to receive the access token
application/x-www-form-urlencoded Yes (Header) Format of the encoding
Authorization: Basic Yes (Header) You need to pass the Base64 encoded string of the client_id:Client_secret

For Authorization header, you need to Base64 encode the value of your client_id:client_secret. As an example, let's say:

To generate Base64 encoded values, you can use the following online resource Based 64 Encoding Tool.

Refresh Access Token

The Access Token has limited lifetime. If your Token expires, you should request a new Access Token using the Refresh Token.

HTTP Request

To refresh Access Token:

curl –X POST <your tenant name here> \
-H 'authorization: Basic <your token here>' \
-H 'content-type:application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'refresh_token=<your token here>'

IDM will return the following in response:

{"access_token":"<your token here>",
"token_type":"Bearer",
"expires_in":10799,
"refresh_token":"<your token here>",
"scope":"admin"}

POST https://[tenant location]/SAAS/auth/oauthtoken

Input parameters

The following parameters need to be specified in the of the request, using the application/x-www-form-urlencoded format:

Parameter Required Description
grant_type=refresh_token Yes (Body) Required parameter
refresh_token Yes (Body) The Refresh Token sent back by Identity Manager during the first Access Token Request.
scope No (Body) The list of scopes separated by space and URL encoded.
Authorization: Basic [base64Encode(clientId + ":" + secret)] Yes (Header) To create your Basic Credentials, create a string with your app’s Client ID and Client Secret, separated by a colon ( : )
Content_Type Yes (Header) Content-Type: application/x-www-form-urlencoded

For Authorization header, you need to Base64 encode the value of your client_id:client_secret. As an example, let's say:

API endpoints

Audit API

This endpoint allows to retrieve audit information from Identity Manager. This information is typically used to generate information about login activity with Identity Manager, along with retrieving various audit information about SaaS IDM instance.

HTTP Request

To query Audit API:

#In this example I am retrieving all audit events of type LOGIN
#and I am restricting the time with toMillis parameter

curl -H 'authorization: Bearer <your token here>' \
<your tenant name here>/analytics/reports/audit?/analytics/reports/audit?fromMillis=1559499975000\&objectType=LOGIN| json_pp

IDM will return the following as a response:

#In this example we see 2 events of LOGIN type
# for the username admin
# the auth method used is password against local directory

{
   "header" : [
      "reports.dateAndTime",
      "reports.userDomain",
      "reports.Event",
      "reports.object",
      ""
   ],
   "data" : [
      [
         "1561399981109",
         "admin (System Domain)",
         "LOGIN (Password (Local Directory))",
         null,
         "{\"baseType\":\"Action\",\"uuid\":\"fe0944c3-5e69-425c-92ee-9db0b099d1aa\",\"timestamp\":1561399981109,\"organizationId\":252221,\"tenantId\":\"<your tenant id>\",\"actorId\":5723506,\"actorUserName\":\"admin\",\"actorDomain\":\"System Domain\",\"actorUuid\":\"35ac32d1-1565-4ab4-ad1a-191120540590\",\"clientId\":null,\"deviceId\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.169 Safari/537.36\",\"workspaceId\":null,\"sourceIp\":\"208.91.2.2\",\"objectType\":\"LOGIN\",\"objectId\":null,\"objectName\":null,\"values\":{\"deviceType\":\"browser\",\"success\":\"true\",\"authMethods\":\"Password (Local Directory)\",\"actorExternalId\":null}}"
      ],
      [
         "1561357380574",
         "admin (System Domain)",
         "LOGIN (Password (Local Directory))",
         null,
         "{\"baseType\":\"Action\",\"uuid\":\"314ee065-744f-4188-b595-0aa961ff00b7\",\"timestamp\":1561357380574,\"organizationId\":252221,\"tenantId\":\"<your tenant id>\",\"actorId\":5723506,\"actorUserName\":\"admin\",\"actorDomain\":\"System Domain\",\"actorUuid\":\"35ac32d1-1565-4ab4-ad1a-191120540590\",\"clientId\":null,\"deviceId\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.169 Safari/537.36\",\"workspaceId\":null,\"sourceIp\":\"66.170.99.1\",\"objectType\":\"LOGIN\",\"objectId\":null,\"objectName\":null,\"values\":{\"deviceType\":\"browser\",\"success\":\"true\",\"authMethods\":\"Password (Local Directory)\",\"actorExternalId\":null}}"
      ]
   ],
   "_links" : {
      "self" : {
         "href" : "/analytics/reports/audit?fromMillis=1561142523041&toMillis=1561401723041&objectType=LOGIN&pageSize=5000&startIndex=0"
      }
   },
   "headerArg" : [
      "",
      "",
      "",
      "",
      ""
   ]
}

GET https://[tenant location]/analytics/reports/audit/

Input parameters

Parameter Required Description
tenant location Yes (URL) Hostname of your tenant
fromMillis No (URL) Filter events no older than this time, milliseconds since epoch, defaults to 3 days ago (now-96 hours)
toMillis No (URL) filter events no newer than this time, milliseconds since epoch, defaults to now.
pageSize No (URL) Max page size of the results, max allowed value is 5000, which is default
startIndex No (URL) Use offset to page through the results
objectType No (URL) Filter specific types of audit events or affected objects. For details, please see the tabel below
action No (URL) Filter event types even further by specifying what action was taken when the event was generated

Types and actions for audit events

There are various types of audit events that can be retrieved. The table below provides a list of most common event types.

Type Description Action
LOGIN Allows to see information about who logged in when and what auth method was used as well as details about IP address, user agent string, etc. failureMessage - the reason if the login attempt failed. authMethods - the authentication methods used. No
Group Allows to see information about group activity in IDM Yes
LAUNCH Allows to see information about who launched what applications and when. Values: success - if the launch attempt was successful. failureMessage - the reason if the launch attempt failed. resourceType - the type of application launched. No
LOGIN_ERROR Allows to see information about any launch failures. Use this action type only if the login did not fail because of wrong user input. It could be a failure because of configuration or system errors. No
DyrectorySyncProfile Allows to see information about directory sync No
AppEntitlement Allows to see information about what applications are entitled to what groups and users Yes
LAUNCH_ERROR User launched an application with an invalid request or if we could not get resource name, UUID or type. Values: failureMessage - the reason if the launch attempt failed.

For the actions, there are several types of action filters available:

Action Description
Create Object was created
Update Object was updated
Delete Object was deleted
Link object was linked
Unlink Object was unlinked

Output parameters

Depending on the objectType retrieved and the action filter specified, API can return various parameters. The table below provides the information about the most used parameters.

Output parameter Description
actorId The userID of the user who performed the event. In the case of a system event, this the value of this attribute will be null. ActorIds are presented in integer format in the case of a user. In the case of a system service, the return will be null.
actorUserName The username of the user who performed the event. In the case of a system event, the value of this attribute will be null. Expected values include both usernames of user accounts in vIDM, as well as system services. Ex: jdoe.
actorDomain The domain of the user who performed the event. In the case of a system event, the value of this attribute will be null. In the case of a user generated event, the domain of the user will be returned. Ex: vmware.com
actorUUid The UUID of the user who performed the event. Return values will always be in standard UUID format. Ex:8c2a83a2-a546-4571-b16c-ed11a8f51725
objectType ObjectType describes the category of event that was recorded. There are many object types that span both end user activities such as authentication or application launch, and admin activities like entitlements. Please, see the table above the describes various object types.
objectId ObjectID represents the unique internal identifier of the object being modified or interacted with. Depending on the object name and type, different ID formats may be returned.
objectName ObjectName describes the object being modified or interacted with. This can take the form of a specific user, application, configuration, or tenant.
objectAction ObjectAction defines which action was taken against the object in an Audit baseType event. As an example, when updating a user or user entitlements, you would find the objectAction "UPDATE". However, in the case of baseType=Action, this attribute will not appear as the action is defined in objectType.
baseType BaseType represents the type of record being returned. There are two possibilities, Audit and Action. Audit events indicate changes to the database as a result of the event. Action events are not directly related to database changes.
timeStamp Time stamp for event in milliseconds UTC since Jan 1, 1970.
uuid Uuid for the specific audit record. This identifier is unique for each record, including multiple instances of the same type of event. Output value is standard UUID format. This value is not particularly useful except when searching for a specific, already known event record. Example UUID: 07b6c947-f025-422f-be2c-3c87b0f3c017
organizationId Unique numerical identifier for the VMware Identity Manager tenant.
tenantId This attribute is the customers tenant identifier. The value should match the prefix of the environment URL in the following format {tenantId}.vmwareidentity.com.
sourceIP This attribute outputs the sourceIP for the machine which issued the request. Values can take on either the IPv4 format. Example IPv4: 168.175.34.12
authMethods This attribute can return one or more authentication methods used for the request. The authentication methods returned correspond directly with the auth adapter labels in the VMware Identity Manager admin console. Multiple auth methods will be listed in comma delimited format. Example: "method1", "method2".

The available Auth Methods that can be returned as part of Audit API response are listed below:

shell