> ## Documentation Index > Fetch the complete documentation index at: https://docs.plainid.io/llms.txt > Use this file to discover all available pages before exploring further. # User List > 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`

    • 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
    HeaderValuecURL Line
    Acceptapplication/json'accept: application/json'
    Content-Typeapplication/json'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 under the Try It\* or the Code Sample tabs. They will then appear in the cURL sample in the correct format to use in your API tool.

    \*Try It function coming soon.

    ## OpenAPI ````json POST /api/runtime/userlist/v3 { "openapi": "3.0.3", "info": { "title": "Authorization APIs", "version": "1.0", "description": "Applications, services, and authorizers use the Authorization APIs to receive the PlainID Access Decision from the PDP", "contact": { "name": "PlainID", "url": "https://plainid.com", "email": "contact@plainid.com" }, "termsOfService": "https://plainid.com/terms", "license": { "name": "Commercial", "url": "https://plainid.com/license" } }, "servers": [ { "description": "United States", "url": "https://tenant-name.us1.plainid.io" }, { "description": "Europe", "url": "https://tenant-name.eu1.plainid.io" }, { "description": "Canada", "url": "https://tenant-name.ca1.plainid.io" }, { "description": "Local PAA", "url": "https://your-paa.acme.local" } ], "tags": [ { "name": "runtime", "description": "runtime" }, { "name": "Cache Management", "description": "Cache invalidation operations for Runtime service" } ], "paths": { "/api/runtime/userlist/v3": { "post": { "tags": [ "runtime" ], "summary": "User List", "operationId": "UserList", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "response" ], "properties": { "asset": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "Asset Template ID (required)" }, "path": { "type": "string", "description": "Unique Identifier of the Asset (required)" }, "assetAttributes": { "type": "object", "description": "(optional)", "properties": { "attribute_1": { "type": "string" }, "attribute_2": { "type": "string" } } } } }, "contextData": { "type": "object", "properties": { "string": { "type": "array", "items": {} } } }, "response": { "type": "array", "items": { "type": "object", "required": [ "action", "entities" ], "properties": { "action": { "type": "string" }, "entities": { "type": "array", "items": { "type": "object", "required": [ "entityType", "uid" ], "properties": { "entityType": { "type": "string" }, "uid": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string" }, "permissionId": { "type": "string" }, "permissionMetadata": { "$ref": "#/components/schemas/permissionMetadata" } } } }, "attributes": { "type": "object", "properties": { "string": { "type": "array", "items": {} } } } } } } } } }, "additionalResponseInfo": { "$ref": "#/components/schemas/additionalResponseInfoResponse" } } }, "examples": { "users list for asset - 200": { "value": { "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": { "value": { "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": { "value": { "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": [] } ] } } } } } }, "400": { "description": "Basic Request - 400 - Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": { "Basic Request - 400 - Bad Request": { "value": {} } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" }, "501": { "description": "Not Implemented" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "entityTypeId": "jwt", "entityId": "bank2", "clientId": "PAG7XRJQCF1XCWTJAZI6Q", "clientSecret": "KIEJNe6as9HbyOEEgWU,)%Q9@GY*Nr7fmB@YuYYW", "entityAttributes": { "acr": [ "1" ], "azp": [ "demo" ], "branch": [ "222" ], "channel": [ "bank" ], "email": [ "bank2@demo.com" ], "email_verified": [ "true" ], "exp": [ "1642170362" ], "iat": [ "1641738362" ], "iss": [ "https://demo.plainid.cloud/auth/realms/demo" ], "jti": [ "e97fe006-5c14-4597-8339-ff707010265f" ], "preferred_username": [ "bank2" ], "scope": [ "profile email" ], "session_state": [ "bcc60c52-42bc-424b-82f6-ceb978cb6a70" ], "sub": [ "b31d9394-7e57-4161-b85a-d67cef419b95" ], "typ": [ "Bearer" ], "user_uuid": [ "0000002" ] } } }, "properties": { "clientId": { "type": "string", "minLength": 1, "description": "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`." }, "clientSecret": { "type": "string", "minLength": 1, "description": "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](https://docs.plainid.io/v1/docs/managing-scope-authentication#setting-up-an-authentication-method-in-the-scope) for more information." }, "asset": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "Asset Template ID (required)" }, "path": { "type": "string", "description": "Unique Identifier of the Asset (required)" }, "actions": { "type": "array", "items": {}, "description": "Name of the Action (optional)" }, "assetAttributes": { "type": "object", "description": "(optional)", "properties": { "attribute_1": { "type": "string" }, "attribute_2": { "type": "string" } } } } }, "contextData": { "type": "object", "description": "Identity Context data for this request.\n\nWhen specifying this parameter, you are requesting information based on a specific parameter and its value.\n\nFor example, Location where the contextData equals a specific branch.\n\nIf not defined, Dynamic groups based on context data will not be considered in the Access Decision.", "properties": { "string": { "type": "array", "items": {} } } }, "environment": { "type": "object", "description": "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.\n\nIf not defined, parameters based on environmental data will not be considered in the Access Decision.", "properties": { "string": { "type": "array", "items": {} } } }, "remoteIp": { "type": "string", "description": "IP address to be used when validating a Policy. Ensure that your IP Ranges are correct based on an [IP calculator](https://www.ipaddressguide.com/cidr). 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": { "type": "number", "description": "To define the offset from UTC time zone.\n\nUsed in Time Condition.", "default": 0, "example": -12 }, "entityTypeId": { "type": "string", "minLength": 1, "description": "Identity Template ID. This is used to distinguish between different Workspaces and Identity Templates." }, "entityTypes": { "type": "array", "description": "This parameter enables you to decrease the payload size by including a list of Identity Types and their Attributes returning in the response. If not specified, all identities from all Identity Types are included in the response.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "attributeList": { "type": "array", "items": {} } } } }, "includeContext": { "type": "boolean", "description": "Show/hide the context data in the response.", "default": false }, "includeAccessPolicy": { "type": "boolean", "description": "Show/hide the name of the Policy in the response that has granted the specified access.", "default": false }, "includeAccessPolicyId": { "type": "boolean", "default": false, "description": "Show/hide the external id of the Policy in the response that granted the specified access." }, "includeAsset": { "type": "boolean", "description": "Show/hide the Asset Attribute of the Assets from the request.", "default": false }, "includeInActiveIdentities": { "type": "boolean", "description": "Show/hide the inactive users in the response.", "default": false }, "includeIdentityAttributes": { "type": "boolean", "description": "Show/hide the Identity Attributeof the Identity in the response.", "default": false }, "accessTokenFormat": { "type": "string", "default": "JSON", "description": "Determines the format of the response – whether `JSON`, `JWT`, or `StandardJWT`." }, "listOfResources": { "type": "string" }, "useCache": { "type": "boolean", "description": "The Attribute determines if the response considers the cache settings or override the cache and perform a full calculation.", "default": true }, "calculateCorrelationAttributes": { "type": "array", "description": "Enables the response to include the Attribute(s) that influenced the access decision, based on predefined correlation logic. The correlation is defined using combinations of `entityType`, `entityAttribute`, and `resourceAttribute`, helping to identify which Identity Attribute matched which resource Attribute during evaluation.\n", "items": { "$ref": "#/components/schemas/correlationAttributeRequest" } }, "operationalFilters": { "type": "array", "description": "These operational filters should affect the Runtime behavior and results by applying additional filtering which is not directly related to Authorization logic.", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/identitySourcesFilterByIDs" }, { "$ref": "#/components/schemas/userListIdentitiesFilterByRule" } ], "discriminator": { "propertyName": "filterType" } } }, "includeCacheInfo": { "type": "boolean", "description": "When true, adds `additionalResponseInfo.cacheUsageInformation` to the response, showing whether the response came from cache (`usedCachedResponse`), the response-cache TTL (`responseCachePeriodSeconds`), and which identity sources served data from cache (`usedCachedIdentityData`).", "default": false } }, "required": [ "clientId", "asset" ] }, "examples": { "User List request": { "value": { "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, "entityTypes": [ { "name": "User", "attributeList": [ "attr1", "attr2" ] } ], "includeContext": false, "includeAccessPolicy": false, "includeAsset": false, "includeInActiveIdentities": false, "includeIdentityAttributes": false, "accessTokenFormat": "JSON", "useCache": true, "calculateCorrelationAttributes": [ { "entityType": "User", "entityAttribute": "uid", "resourceAttribute": "resource_attr" } ], "operationalFilters": [ { "filterType": "identitySourcesFilterByIDs", "filterProperties": { "filterAction": "INCLUDE", "objectsList": [ "sourceID_123", "sourceID_456" ] } }, { "filterType": "userListIdentitiesFilterByRule", "filterProperties": { "filterDetails": [ { "sourceId": "c9a74c7d-e81c-4d16-b22e-7dbf8921f7ef", "filtersRelation": "OR", "filters": [ { "attribute": "uid", "operator": "IN", "values": [ "user1", "user2" ] } ] } ] } } ] } } } } }, "description": "" }, "description": "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. \n\nNote: The User List end point is used primarily for reporting data. There are time and amount constraints based on your Identity sources.\n

    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`

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

    \n

    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
    HeaderValuecURL Line
    Acceptapplication/json'accept: application/json'
    Content-Typeapplication/json'content-type: application/json'

    \n

    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 under the Try It\\* or the Code Sample tabs. They will then appear in the cURL sample in the correct format to use in your API tool.

    \\*Try It function coming soon.

    ", "parameters": [ { "schema": { "type": "string" }, "name": "X-Client-Id", "in": "header", "description": "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`.", "required": false }, { "schema": { "type": "string" }, "name": "X-Client-Secret", "in": "header", "description": "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](https://docs.plainid.io/v1/docs/managing-scope-authentication#setting-up-an-authentication-method-in-the-scope) for more information.", "required": false } ] } } }, "components": { "schemas": { "permissionMetadata": { "type": "object", "minProperties": 1, "description": "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. " }, "additionalResponseInfoResponse": { "type": "object", "properties": { "identitySources": { "type": "object", "properties": { "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/identitySourceInfo" } }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/identitySourceInfo" } } } }, "cacheUsageInformation": { "type": "object", "description": "Appears only when the request sets `includeCacheInfo=true`.", "properties": { "usedCachedResponse": { "type": "boolean", "description": "`true` when the entire response was served from the response (scope) cache.
    `false` when the response was freshly calculated: a cache miss, `useCache=false`, no response-cache TTL configured for the scope or a request sent right after the response cache was invalidated." }, "responseCachePeriodSeconds": { "type": "integer", "description": "The scope's configured response-cache TTL in seconds." }, "usedCachedIdentityData": { "type": "array", "description": "The identity sources whose attribute data was served from the identity cache during this request's identity retrieval. Empty when the whole response came from the response cache (identity retrieval never ran, see `usedCachedResponse`), when every identity source configured for this request had caching disabled, or when every source was fetched fresh (including a partial fetch after a source's cache entry expired or was invalidated). ", "items": { "type": "object", "properties": { "sourceId": { "type": "string", "description": "The Identity Source ID" }, "sourceName": { "type": "string", "description": "The Identity Source's name." }, "cachePeriodSeconds": { "type": "integer", "description": "The Source's own configured identity-cache TTL, in seconds. Sources with identity caching disabled do not appear here." } } } } } } } }, "correlationAttributeRequest": { "type": "object", "properties": { "entityType": { "type": "string" }, "entityAttribute": { "type": "string" }, "resourceAttribute": { "type": "string" } } }, "identitySourcesFilterByIDs": { "allOf": [ { "$ref": "#/components/schemas/operationalFilter" }, { "type": "object", "properties": { "filterProperties": { "type": "object", "required": [ "filterAction", "objectsList" ], "properties": { "filterAction": { "type": "string", "enum": [ "INCLUDE", "EXCLUDE" ] }, "objectsList": { "type": "array", "items": { "type": "string", "description": "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": { "allOf": [ { "$ref": "#/components/schemas/operationalFilter" }, { "type": "object", "properties": { "filterProperties": { "type": "object", "required": [ "filterDetails" ], "properties": { "filterDetails": { "type": "array", "items": { "type": "object", "required": [ "sourceId", "filtersRelation", "filters" ], "properties": { "sourceId": { "type": "string", "description": "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": { "type": "string", "enum": [ "OR", "AND" ] }, "filters": { "type": "array", "items": { "type": "object", "required": [ "attribute", "operator", "values" ], "properties": { "attribute": { "type": "string", "description": "For more information on where to locate attributes, see Managing Identity Attributes." }, "operator": { "type": "string", "enum": [ "IN", "EQUALS" ] }, "values": { "type": "array", "items": { "type": "string" } } } } } } } } } } } } ] }, "identitySourceInfo": { "type": "object", "properties": { "sourceId": { "type": "string" }, "sourceName": { "type": "string" }, "message": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } } } }, "operationalFilter": { "type": "object", "required": [ "filterType" ], "properties": { "filterType": { "type": "string" } }, "discriminator": { "propertyName": "filterType" } } } } } ````