User List

30 Mar 2025
6 Minutes to read

Print
Dark
Light
PDF

User List

Updated on 30 Mar 2025
6 Minutes to read

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Post

/api/runtime/userlist/v3

The User List API call is an open-ended question for a specific Asset. It returns the list of users, their associated Attributes and which action they are allowed to perform on a specific Asset.

Note: The User List end point is used primarily for reporting data. There are time and amount constraints based on your Identity sources.

Notice

When accessing the Authorization APIs, the URL base/prefix, according to your PlainID PDP Location

United States Cloud PDP - `https://tenant-name.us1.plainid.io`

Canadian Cloud PDP - `https://tenant-name.ca1.plainid.io`

European Cloud PDP - `https://tenant-name.eu1.plainid.io`

Local PAA - `https://your-paa.acme.local`

For more information on which Asset Types to use with your PAA or Cloud PDP, refer to Managing Asset Types.

Important note about headers

Refer to the headers below to modify your cURL sample. Check if the following headers are in the sample, if not, ensure you add it to your cURL sample before pasting into your API tool.

Headers

*Required

Header	Value	cURL Line
content-type	`application/json`	`-H 'Content-Type: application/json' `

cURL Sample Guidelines

In order for the relevant parameters to appear in the cURL sample, you can input the values in the interactive API console on the right. They will then appear in the cURL sample on the bottom of the page in the correct format.

Header parameters

X-Client-Id

string

Client ID of the Scope
The clientId is required, ensure that it is defined either in the header as X-Client-Id or in the body as clientId.

X-Client-Secret

string

Client Secret ID of the Scope.
You can also authenticate with an Authorization Token (in your API tool). Note that the X-Client-Id is still required, whether in the header or the body. Refer to Setting up an Authentication Method for more information.

Body parameters

User List request

{
  "clientId": "[ClientID]",
  "clientSecret": "[ClientSecret]",
  "asset": {
    "resourceType": "Account US",
    "path": "Transfer US 5000",
    "actions": [
      "Access"
    ],
    "assetAttributes": {
      "order_type": [
        "credit_card"
      ],
      "customer_type": [
        "private"
      ]
    }
  },
  "contextData": {
    "string": [
      "string"
    ]
  },
  "environment": {
    "string": [
      "string"
    ]
  },
  "remoteIp": "string",
  "timeZoneOffset": 0.0,
  "entityTypes": [
    "string"
  ],
  "includeContext": false,
  "includeAccessPolicy": false,
  "includeAsset": false,
  "includeInActiveIdentities": false,
  "includeIdentityAttributes": false,
  "accessTokenFormat": "JSON",
  "useCache": true,
  "calculateCorrelationAttributes": [
    "string"
  ]
}

Expand All

object

clientId

string Required

Client ID of the Scope
The Client ID is required, ensure that it is defined either in the header as X-Client-Id or in the body as clientId.

Min length1

clientSecret

string

Min length1

asset

object Required

resourceType

string

Asset Template ID (required)

path

string

Unique Identifier of the Asset (required)

actions

Array

Name of the Action (optional)

assetAttributes

object

(optional)

attribute_1

string

attribute_2

string

contextData

object

Identity Context data for this request.

When specifying this parameter, you are requesting information based on a specific parameter and its value.

For example, Location where the contextData equals a specific branch.

If not defined, Dynamic groups based on context data will not be considered in the Access Decision.

string

Array

environment

object

Environmental parameters need to be defined in policies as request. (in Assetrules or Conditions) and also sent in the authorization request. Only the assets that match what will be sent in the request will come back.

If not defined, parameters based on environmental data will not be considered in the Access Decision.

string

Array

remoteIp

string

IP address to be used when validating a Policy. Ensure that your IP Ranges are correct based on an IP calculator. If not defined, the IP considered in the calculation is taken from the X-Forwarded-For (Request header). If not defined,the IP considered in the calculation is taken from the X-Forwarded-For (Request header).

timeZoneOffset

number

To define the offset from UTC time zone.

Used in Time Condition.

Default0

Example-12

entityTypeId

string

Identity Template ID. This is used to distinguish between different Workspaces and Identity Templates.

Min length1

entityTypes

Array

Entity Type IDs

includeContext

boolean

Show/hide the context data in the response.

Defaultfalse

includeAccessPolicy

boolean

Show/hide the name of the Policy in the response that has granted the specified access.

Defaultfalse

includeAccessPolicyId

boolean

Show/hide the external id of the Policy in the response that granted the specified access.

Defaultfalse

includeAsset

boolean

Show/hide the Asset Attribute of the Assets from the request.

Defaultfalse

includeInActiveIdentities

boolean

Show/hide the inactive users in the response.

Defaultfalse

includeIdentityAttributes

boolean

Show/hide the Identity Attributeof the Identity in the response.

Defaultfalse

accessTokenFormat

string

Determines the format of the response – whether JSON, JWT, or StandardJWT.

Default"JSON"

listOfResources

string

useCache

boolean

The Attribute determines if the response considers the cache settings or override the cache and perform a full calculation.

Defaulttrue

calculateCorrelationAttributes

Array

Provides the ability to present the Attribute that is responsible for the investigated access, based on defined correlation Attributes according to the

· entityType

· entityAttribute

· resourceAttribute

operationalFilters

Array of object

These operational filters should affect the Runtime behavior and results by applying additional filtering which is not directly related to Authorization logic.

object

#content#

OneOf

identitySourcesFilterByIDs

object (identitySourcesFilterByIDs)

filterType

string Required

filterProperties

object

filterAction

string Required

Valid values[ "INCLUDE", "EXCLUDE" ]

objectsList

Array of string Required

string

Input your sourceID/s here. For information on the sourceID parameter and where to locate it, check out Managing Attribute Sources in the PlainID documentation.

userListIdentitiesFilterByRule

object (userListIdentitiesFilterByRule)

filterType

string Required

filterProperties

object

filterDetails

Array of object Required

object

sourceId

string Required

Input your sourceID/s here. For information on the sourceID parameter and where to locate it, check out Managing Attribute Sources in the PlainID documentation.

filtersRelation

string Required

Valid values[ "OR", "AND" ]

filters

Array of object Required

object

attribute

string Required

For more information on where to locate attributes, see Managing Identity Attributes.

operator

string Required

Valid values[ "IN", "EQUALS" ]

values

Array of string Required

string

Responses

200

users list for asset - 200

{
  "response": [
    {
      "action": "Access",
      "entities": [
        {
          "entityType": "bank_users",
          "uid": "UX-12349"
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12348"
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12347"
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12346"
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12345"
        }
      ]
    },
    {
      "action": "TestAction",
      "entities": []
    }
  ]
}

includeIdentityAttributes - 200

{
  "response": [
    {
      "action": "Access",
      "entities": [
        {
          "entityType": "bank_users",
          "uid": "UX-12349",
          "attributes": {
            "uid": [
              "UX-12349"
            ],
            "location": [
              "Alabama"
            ],
            "department": [
              "Mortgage"
            ],
            "branch": [
              "vitae nisl"
            ]
          }
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12348",
          "attributes": {
            "uid": [
              "UX-12348"
            ],
            "location": [
              "Alabama"
            ],
            "department": [
              "Loans"
            ],
            "branch": [
              "varius integer"
            ]
          }
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12347",
          "attributes": {
            "uid": [
              "UX-12347"
            ],
            "location": [
              "Alabama"
            ],
            "department": [
              "Savings"
            ],
            "branch": [
              "egestas metus"
            ]
          }
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12346",
          "attributes": {
            "uid": [
              "UX-12346"
            ],
            "location": [
              "Alabama"
            ],
            "department": [
              "Mortgage"
            ],
            "branch": [
              "ac est"
            ]
          }
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12345",
          "attributes": {
            "uid": [
              "UX-12345"
            ],
            "location": [
              "Alabama"
            ],
            "department": [
              "Savings"
            ],
            "branch": [
              "sapien quis"
            ]
          }
        }
      ]
    },
    {
      "action": "TestAction",
      "entities": []
    }
  ]
}

includeAccessPolicy and includeAccessPolicyId - 200

{
  "response": [
    {
      "action": "Access",
      "entities": [
        {
          "entityType": "bank_users",
          "uid": "UX-12349",
          "permissions": {
            "permission": [
              "Manage consumers accounts in branch"
            ],
            "permissionId": [
              "p1"
            ]
          }
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12348",
          "permissions": {
            "permission": [
              "Manage consumers accounts in branch"
            ],
            "permissionId": [
              "p1"
            ]
          }
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12347",
          "permissions": {
            "permission": [
              "Manage consumers accounts in branch"
            ],
            "permissionId": [
              "p1"
            ]
          }
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12346",
          "permissions": {
            "permission": [
              "Manage consumers accounts in branch"
            ],
            "permissionId": [
              "p1"
            ]
          }
        },
        {
          "entityType": "bank_users",
          "uid": "UX-12345",
          "permissions": {
            "permission": [
              "Manage consumers accounts in branch"
            ],
            "permissionId": [
              "p1"
            ]
          }
        }
      ]
    },
    {
      "action": "TestAction",
      "entities": []
    }
  ]
}

Expand All

object

asset

object

resourceType

string

Asset Template ID (required)

path

string

Unique Identifier of the Asset (required)

assetAttributes

object

(optional)

attribute_1

string

attribute_2

string

contextData

object

string

Array

response

Array of object

object

action

string

entities

Array of object

object

entityType

string

uid

string

permissions

Array of object

object

permission

string

permissionId

string

permissionMetadata

object (permissionMetadata)

Additional response metadata. This response is only returned when the includeAccessPolicy is set to true, and when the permissionMetadata object contains one or more properties

attributes

object

string

Array

400

Basic Request - 400 - Bad Request

{}

object

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

501

Not Implemented

Was this article helpful?

What's Next

Policy List