List Users

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 the users belong to and the application 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.

This API is version v1.

Required Roles

  • Service Administrator

  • Any predefined role and the Access Control - Manage application role

  • Any predefined role and the Access Control - View application role

REST Resource

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

Note:

Before using the REST resources, you must understand how to access the REST resources and other important concepts. See Implementation Best Practices for Cloud EPM REST APIs. Using this REST API requires prerequisites. See Prerequisites.

Table 12-38 Tasks for List Users

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

Request

Supported Media Types: application/json

Table 12-39 Request Parameters

Name Description Type Required Default
userlogin

Get the users matching the specified userlogin.

Payload No Return all users
memberof
  • 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
roles
  • 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
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",
  "memberof": true,
  "roles": true,
  "userattribute": "jack"
}

Response

Supported Media Types: application/json

Table 12-40 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

The following examples show the contents of the response body in JSON format:

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" 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"
    }
  ]
} 

Example 3: REST API Issued with "userlogin", "memberof " and "roles " 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",
      "memberof": {
        "groups": [
          {
            "groupname": "Analyst",
            "description": "analyst",
            "type": "EPM"
          },
          {
            "groupname": "InteractiveUser",
            "description": "UsedforaccessassignmentsforPowerUsers",
            "type": "EPM"
          }
        ]
      },
      "roles": [
        {
          "rolename": "AdHoc-ReadOnlyUser",
          "id": "HP: 0017"
        },
        {
          "rolename": "AdHoc-User",
          "id": "HP: 0015"
        }
      ]
    }
  ]
}

Example 4: 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","memberof":true,"roles":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","memberof":true,"roles":true}' 'https://<BASE-URL>/interop/rest/security/v1/users/list'