List Users (v1)

The List Users REST API generates a list of available users in the environment.

The API identifies the userlogin, firstname, lastname, and email. Additionally, it can provide information about the EPM groups, IDCS groups, application roles, and granular roles assigned to the users. Users can be retrieved based on specific user login or any matching user attribute (first name, last name, user login, email).

The API is synchronous and returns the outcome of the operation in the response. Any non-zero status indicates failure in listing users.

The optional indirect parameter controls whether the API returns only direct associations or both direct and indirect associations.

Required Roles

Service Administrator
Any application role and the Access Control - Manage granular role
Any application role and the Access Control - View granular role

REST Resource

POST /interop/rest/security/v1/users/list

Table 2-39 Tasks for List Users

Task	Request	REST Resource
List Users	POST	`/interop/rest/security/v1/users/list`

Request

Supported Media Types: application/json

Table 2-40 Request Parameters

Name	Description	Type	Required	Default
`userlogin`	Get the users matching the specified `userlogin`.	Payload	No	Return all users
`epmgroups`	true: Returns the list of EPM groups that users belong to, if any. false: Does not return the list of EPM groups that users belong to, if any.	Payload	No	False
`granularroles`	true: Returns the list of granular roles assigned to users, if any. false: Does not return the list of granular roles assigned to users, if any.	Payload	No	False
`idcsgroups`	true: Returns the list of IDCS groups that users belong to, if any. false: Does not return the list of IDCS groups that users belong to, if any.	Payload	No	False
`applicationroles`	true: Returns the list of application roles assigned to users, if any. false: Does not return the list of application roles assigned to users, if any.	Payload	No	False
`indirect`	true: Returns both direct and indirect groups and roles that users belong to, if any. false: Returns only direct groups and roles that users belong to, if any.	Payload	No	False
`userattribute`	Get the users matching the specified user attribute (case-insensitive) with any one of these user attributes: `userlogin` `firstname` `lastname` `email`	Payload	No	Returns all users

Example URL and Payload

https://<BASE-URL>/interop/rest/security/v1/users/list

{
  "userlogin": "john",
  "epmgroups": true,
  "granularroles": true,
  "idcsgroups": true
  "applicationroles": true,
  "indirect": true,
  "userattribute": "jack"
}

Response

Supported Media Types: application/json

Table 2-41 Response Parameters

Name	Description
`links`	Detailed information about the link and HTTP call type
`status`	Status of the operation 0: Operation succeeded 1: Operation failed
`error`	Detailed information about the error
`details`	User details

Examples of Response Body

Example 1: REST API issued without any Payload Completes without Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/users/list",
    "action": "POST"
  },
  "status": 0,
  "error": null,
  "details": [
    {
      "userlogin": "Jade",
      "firstname": "Jade",
      "lastname": "Clark",
      "email": "jade.clark@example.com"
    },
    {
      "userlogin": "Jeff",
      "firstname": "Jeff",
      "lastname": "Clark",
      "email": "jeff.clark@example.com"
    },
    {
      "userlogin": "john",
      "firstname": "john",
      "lastname": "kennedy",
      "email": "john.kennedy@example.com"
    }
  ]

Example 2: REST API issued with "userlogin", "epmgroups ", "granularroles ", "idcsgroups ", and "applicationroles " in Payload Completes without Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/users/list",
    "action": "POST"
  },
  "status": 0,
  "error": null,
  "details": [
    {
      "userlogin": "john",
      "firstname": "john",
      "lastname": "kennedy",
      "email": "john.kennedy@example.com",
      "epmgroups": [
        {
          "groupname": "Analyst",
          "description": "analyst",
          "type": "EPM"
        },
        {
          "groupname": "InteractiveUser",
          "description": "UsedforaccessassignmentsforPowerUsers",
          "type": "EPM"
        }
      ],
      "idcsgroups": [
        {
          "groupname": "Sales-EU",
          "description": "sales euratop",
          "type": "IDCS"
        },
        {
          "groupname": "Sales-US",
          "description": "Sales United States",
          "type": "IDCS"
        }
      ],
      "granularroles": [
        {
          "rolename": "AdHoc-ReadOnlyUser",
          "id": "HP: 0017"
        },
        {
          "rolename": "AdHoc-User",
          "id": "HP: 0015"
        }
      ],
      "applicationroles": [
        {
          "rolename": "Service Administrator",
          "id": "HUB: 001"
        },
        {
          "rolename": "Power User",
          "id": "HUB: 002"
        }
      ]
    }
  ]
}

Example 3: REST API Completes with Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/users/list",
    "action": "POST"
  },
  "status": 1,
  "error": {
    "errorcode": "EPMCSS-21193",
    "errormessage": "Failed to get Users. Authorization failed. Please provide valid authorized User."
  },
  "details": null
}

Sample cURL Command Basic Auth

curl -X POST -s -u '<USERNAME>:<PASSWORD>' -H 'Content-Type: application/json' 'https://<BASE-URL>/interop/rest/security/v1/users/list'

curl -X POST -s -u '<USERNAME>:<PASSWORD>' -H 'Content-Type: application/json' -d '{"userlogin":"john"}' 'https://<BASE-URL>/interop/rest/security/v1/users/list'

curl -X POST -s -u '<USERNAME>:<PASSWORD>' -H 'Content-Type: application/json' -d '{"userlogin":"john","epmgroups":true,"granularroles":true,"idcsgroups":true,"applicationroles":true,"indirect":true }' 'https://<BASE-URL>/interop/rest/security/v1/users/list'

Sample cURL Command OAuth 2.0

curl -X POST --header "Authorization: Bearer <OAUTH_ACCESS_TOKEN>" -H'Content-Type: application/json' 'https://<BASE-URL>/interop/rest/security/v1/users/list'

curl -X POST --header "Authorization: Bearer <OAUTH_ACCESS_TOKEN>" -H'Content-Type: application/json' -d '{"userlogin":"john"}' 'https://<BASE-URL>/interop/rest/security/v1/users/list'

curl -X POST --header "Authorization: Bearer <OAUTH_ACCESS_TOKEN>" -H'Content-Type: application/json' -d '{"userlogin":"john","epmgroups":true,"granularroles":true,"idcsgroups":true,"applicationroles":true,"indirect":true}' 'https://<BASE-URL>/interop/rest/security/v1/users/list'