User Access Token

07 Aug 2024
11 Minutes to read

Print
Dark
Light
PDF

User Access Token

Updated on 07 Aug 2024
11 Minutes to read

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Post

/api/runtime/token/v3

The User Access Token API call is an open-ended question for a specific user, returning the list of allowed Assets and their associated actions for a specific application. The API presents a generic request based primarily on the Identity and will return all requested Assets and Actions that are configured for this user in a single token. This API enables the scope to cache the list of authorized Assets for a user within the Application session, thus reducing the overall performance involved in enforcing access.

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 Access Token

{
  "entityId": "string",
  "clientId": "string",
  "clientSecret": "string",
  "entityTypeId": "string",
  "assetList": {
    "type": [
      {
        "template": "string",
        "path": "string",
        "assetAttributes": {
          "attribute_1": [
            "string"
          ],
          "attribute_2": [
            "string"
          ]
        }
      }
    ]
  },
  "entityAttributes": {
    "string": [
      "value"
    ]
  },
  "contextData": {
    "string": [
      "string"
    ]
  },
  "environment": {
    "string": [
      "string"
    ]
  },
  "remoteIp": "192.168.0.1",
  "timeZoneOffset": 0.0,
  "resourceTypes": {
    "name": "resource_01_name",
    "attributeList": [
      "price",
      "color"
    ],
    "actions": [
      "edit",
      "view"
    ]
  },
  "includeContext": false,
  "includeAccessPolicy": false,
  "includeAccessPolicyId": false,
  "includeAssetAttributes": false,
  "includeIdentity": false,
  "accessTokenFormat": "JSON",
  "useCache": true
}

Expand All

object

entityId

string Required

Unique identifier of the Identity

Min length1

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

entityTypeId

string

Identity Template ID

Min length1

entityAttributes

object

List of Identity Attributes and their values.

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

string

Array

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 Asset rules 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, parametes based on emviromental data will not be considered in the Access Decision.

string

Array

remoteIp

string (ipv4)

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).

Min length1

timeZoneOffset

number

To define the offset from UTC time zone. Used in Time Condition.

Default"0"

Example-12

assetList

object

Contains a list of the Asset's unique identifier and attributes:

template

string

Asset Template ID

path

string

Asset Unique Identifier

assetAttributes

object

attribute_1

Array of string

string

attribute_2

Array of string

string

resourceTypes

Array of object

This parameter enables you to decrease the payload size by including a list of Asset Types, their Attributes, and/or associated Actions, which also return in the response. If not specified, all resources from all Resource Types will be included. Ensure you are sending either resourceTypes or allResourceTypes in the request. Sending both will result in an error.

object

name

string Required

The name of the Resource Type is the Asset Template ID. This can be found in the Asset Type Settings.

attributeList

Array of string

A list of Attributes. This can be found in the Asset Type Settings. The list of Attributes are applied on each resourceType in the request, and if applicable, will be part of the response. If no Attributes are specified, Attributes are not included in the response,.

Ensure that the includeAssetAttributes parameter is set to true for the attributeList parameter to work. If set to false, Attributes are not returned.

string

actions

Array of string

The name of the Action/s. This can be found in the Asset Type Settings. The list of Actions are applied on each resourceType in the request, and if applicable, will be part of the response. If no Actions are specified, all Actions for each resourceType are included in the response.

string

allResourceTypes

object (allResourceTypesInput)

This parameter enables you to decrease the payload size by including a list of Asset Types, their Attributes, and/or associated Actions, which also return in the response. If not specified, all resources from all Resource Types will be included. Ensure you are sending either allResourceTypes or resourceTypes in the request. Sending both will result in an error.

attributeList

Array of string

A list of Attributes. This can be found in the Asset Type Settings. The list of Attributes are applied on each resourceType in the request, and if applicable, will be part of the response. If no Attributes are specified, all Attributes for each resourceType are included in the response.

Ensure that the includeAssetAttributes parameter is set to true for the attributeList parameter to work. If set to false, Attributes are not returned.

string

actions

Array of string

string

includeContext

boolean

Show/hide the context data in the response.

Default"False"

includeAccessPolicy

boolean

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

Default"False"

includeAccessPolicyId

boolean

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

Default"False"

includeAssetAttributes

boolean

Show/hide the Asset Attribute of the Assets in the response. If using the attributeList in the resourceType or allResourceTypes parameters, ensure that this parameter is set to true.

Default"False"

includeIdentity

boolean

Show/hide the Identity Attribute of the Identity in the response.

Default"False"

accessTokenFormat

string

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

Default"JSON/JWT"

useCache

boolean

The Attribute will determine if the response will consider the cache settings or override the cache and preforming full calculation.

Default"True"

combinedMultiValue

boolean

Determines the evaluation of Identity Attributes relationship in access decision.

Default"False"

assetContext

Array of object (assetContextRequestItem)

object

key

string

An auto-generated key to set the correlation between the requested object and the response object (optional). When working with a single assetContext object, use the “singleObjectResponse” value to align to the original structure response.

resourceType

string Required

path

string

action

string

assetAttributes

object

attribute_1

Array of string

string

attribute_2

Array of string

string

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

OneOf

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.

skipUnneededOrUnavailableIdentitySources

boolean

The Attribute will determine if the calculation will skip unneeded or unavailable Identity sources. Refer to the Authorization API article for more information.

Default"False"

includePartialIdentitySourcesIndication

boolean

Show/hide additionalResponseInfo in the response.

Default"False"

Responses

200

Default Response

{
  "tokenValidity": 0,
  "response": [
    {
      "access": [
        {
          "path": "27iX3j",
          "attributes": {
            "Path": [
              "27iX3j"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        },
        {
          "path": "72xQ9i",
          "attributes": {
            "Path": [
              "72xQ9i"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        },
        {
          "path": "05mZ1f",
          "attributes": {
            "Path": [
              "05mZ1f"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        }
      ]
    }
  ],
  "contextData": null
}

includeAccessPolicy

{
  "tokenValidity": 0,
  "response": [
    {
      "access": [
        {
          "path": "27iX3j",
          "attributes": {
            "Path": [
              "27iX3j"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "permission": "Manage consumers accounts in branch",
              "permissionId": "p1",
              "action": "View"
            }
          ]
        },
        {
          "path": "72xQ9i",
          "attributes": {
            "Path": [
              "72xQ9i"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "permission": "Manage consumers accounts in branch",
              "permissionId": "p1",
              "action": "View"
            }
          ]
        },
        {
          "path": "05mZ1f",
          "attributes": {
            "Path": [
              "05mZ1f"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "permission": "Manage consumers accounts in branch",
              "permissionId": "p1",
              "action": "View"
            }
          ]
        }
      ]
    }
  ],
  "contextData": null
}

includeAssetAttributes - False

{
  "tokenValidity": 0,
  "response": [
    {
      "access": [
        {
          "path": "27iX3j",
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        },
        {
          "path": "72xQ9i",
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        },
        {
          "path": "05mZ1f",
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        }
      ],
      "contextData": {}
    }
  ]
}

includeIdentity

{
  "tokenValidity": 0,
  "response": [
    {
      "access": [
        {
          "path": "27iX3j",
          "attributes": {
            "Path": [
              "27iX3j"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        },
        {
          "path": "72xQ9i",
          "attributes": {
            "Path": [
              "72xQ9i"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        },
        {
          "path": "05mZ1f",
          "attributes": {
            "Path": [
              "05mZ1f"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        }
      ]
    }
  ],
  "identity": {
    "type": "02a89b66-0a15-4b8e-be6d-84cb99da9b13",
    "typeName": "User",
    "attributes": {
      "First_Name": [
        "Araldo"
      ],
      "uid": [
        "xB724129"
      ],
      "User_Branch": [
        "San Jose"
      ],
      "Last_Name": [
        "Baudou"
      ],
      "ID": [
        "xB724129"
      ],
      "title": [
        "Teller"
      ],
      "User_Type": [
        "Internal"
      ]
    }
  },
  "contextData": null
}

includeContext

{
  "tokenValidity": 0,
  "response": [
    {
      "access": [
        {
          "path": "27iX3j",
          "attributes": {
            "Path": [
              "27iX3j"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        },
        {
          "path": "72xQ9i",
          "attributes": {
            "Path": [
              "72xQ9i"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        },
        {
          "path": "05mZ1f",
          "attributes": {
            "Path": [
              "05mZ1f"
            ],
            "Account Type": [
              "private"
            ],
            "Account Branch": [
              "San Jose"
            ]
          },
          "resourceType": "Bank Accounts",
          "actions": [
            {
              "action": "View"
            }
          ]
        }
      ]
    }
  ],
  "contextData": {
    "partner_id": "724f9f9b-af24-42fc-b97d-b399042ef00d"
  }
}

Expand All

AnyOf

tokenResponse

tokenValidity

integer

response

Array of object

object

access

Array of object

object

path

string

attributes

object

resourceType

string

actions

Array of object

object

action

string

permission

string

permissionId

string

contextData

object

attribute

Array of string

string

identity

object (identityResponse)

type

string

typeName

string

attributes

object

additionalResponseInfo

object (additionalResponseInfoResponse)

identitySources

object

skipped

Array of object (identitySourceInfo)

object

sourceId

string

sourceName

string

message

string

attributes

Array of string

string

failed

Array of object (identitySourceInfo)

object

sourceId

string

sourceName

string

message

string

attributes

Array of string

string

assetContextTokenResponse

data

Array of object

object

assetContext

object (assetContextResponseItem)

AnyOf

object

key

string

object

resourceType

string

path

string

action

string

assetAttributes

object

attribute_1

Array of string

string

attribute_2

Array of string

string

output

object

accessResponse

object (tokenResponse)

tokenValidity

integer

response

Array of object

object

access

Array of object

object

path

string

attributes

object

resourceType

string

actions

Array of object

object

action

string

permission

string

permissionId

string

contextData

object

attribute

Array of string

string

identity

object (identityResponse)

type

string

typeName

string

attributes

object

additionalResponseInfo

object (additionalResponseInfoResponse)

identitySources

object

skipped

Array of object (identitySourceInfo)

object

sourceId

string

sourceName

string

message

string

attributes

Array of string

string

failed

Array of object (identitySourceInfo)

object

sourceId

string

sourceName

string

message

string

attributes

Array of string

string

error

string

400

Bad Request

400 Bad Request

{
  "bank_users1 is not a valid identity type": null
}

object

401

Unauthorized

401 Unauthorized - MissingSecret

{
  "Missing secret": null
}

object

403

Forbidden

403 Forbidden - InvalidSecret

{
  "Invalid secret": null
}

object

500

Internal Server Error

500 - Request

{
  "Asset provider is missing in config": "Accounts"
}

object

501

Example response

generic_error_skeleton

{
  "errors": [
    {
      "id": "XXXX",
      "code": "YYYY",
      "message": "Invalid request"
    }
  ]
}

object

errors

Array

string

Min length1

code

string

Min length1

message

string

Min length1

Was this article helpful?

What's Next

User Access Token