JSON PDP API request and response flow
The JSON policy decision point (PDP) API provides an HTTP REST API for attribute-based access control based on policies configured in the PingAuthorize Server Policy Decision Service.
The JSON PDP API is implemented with an individual decision request endpoint, an individual query decision request endpoint, and a batch request endpoint that consuming application servers can access using POST requests to the /governance-engine, /governance-engine/query, or /governance-engine/batch paths, respectively. You can find more information about the /query endpoint in Policy queries.
The HTTP request must include the appropriate Content-Type and Accept headers, and request bodies must be valid JSON in the expected request format.
The endpoint paths and headers are listed in the following table.
| JSON PDP API Endpoint path | Action | Content-Type/Accept | Request data |
|---|---|---|---|
|
POST |
|
JSON |
|
POST |
|
JSON |
|
POST |
|
JSON |
A successful JSON PDP API request goes through the following flow:
-
The client makes the JSON request, which is received by the JSON PDP API. The API forwards the request to the Policy Decision Service.
-
When the Policy Decision Service returns a response, the API sends the response to the client.
|
The Policy Enforcement Point (PEP) must apply any obligations or statements. Learn more about making JSON PDP API requests in the JSON PDP API Reference. |
JSON PDP API request format
Individual requests
A valid JSON PDP API request is a simple JSON object that a client application sends to the Policy Decision Service. Policies can match a decision request by service, domain, action, or other attributes.
The following table describes the fields in a valid JSON PDP API request:
| Field | Value type | Required | Trust Framework type | Example value |
|---|---|---|---|---|
|
String |
Optional |
Domain |
|
|
String |
Optional |
Action |
|
|
String |
Optional |
Service |
|
|
String |
Optional |
Identity Provider |
|
|
Map <string, string> |
Required |
Attribute map |
|
|
Although the |
The following is an example of a valid individual JSON request:
{
"domain": "Sales.Asia Pacific",
"action": "Retrieve",
"service": "Mobile.Landing page",
"identityProvider": "Social Networks.Spacebook",
"attributes": {
"Prospect name": "B. Vo"
}
}The following image shows how Prospect name is defined in the Policy Editor. In this example, the Prospect name attribute has a Request resolver and a Type of string.
|
The Trust Framework attribute name must match the key of the |
Batch requests
Batch requests consist of an array named requests that contains individual JSON requests.
The following example shows a valid batch JSON request:
{
"requests": [
{
"domain": "Sales.Asia Pacific",
"action": "Retrieve",
"service": "Mobile.Landing page",
"identityProvider": "Social Networks.Spacebook",
"attributes": {
"Prospect name": "B. Vo"
}
},
{
"domain": "Sales.EMEA",
"action": "Search",
"service": "Mobile.Users search",
"identityProvider": "Social Networks.Chirper",
"attributes": {
"Prospect name": "A. Mann"
}
}
]
}Query requests
Query requests differ from individual and batch JSON requests in allowing the following types of attributes:
-
Unbounded: A request attribute without any value specified. These attributes' values can be populated at decision runtime by making calls to external services.
-
Multivalued: A request attribute with multiple values specified.
Query requests consist of the following fields:
-
query: An array containing the following elements:-
attribute: The full name of an unbounded, multivalued, or standard authorization attribute. -
values: An optional array defining the values of the attribute. If you include more than one value in this array, the JSON PDP API treats the attribute as multivalued. If the attribute is unbounded, do not include this array.You cannot leave the
valuesarray empty in a query request sent in embedded policy decision point (PDP) mode. If you leave thevaluesarray empty in a request sent in external PDP mode, the relevant attribute is treated as an unbounded attribute.
The
queryarray has the following constraints:-
At most one attribute can be included without values (unbounded).
-
At most two attributes can be multivalued.
-
At most three attributes can be included in the array, but not all three can be multivalued or unbounded.
-
-
context(optional): A JSON object containing the fields included in a typical individual JSON request.
You can include single-valued attributes in the query or context fields. Including a single-valued attribute in the query field adds that attribute and its value to each results array element in the query response.
The following example asks, "Which actions can Joe perform on the account?":
{
"query": [
{
"attribute": "action"
},
{
"attribute": "Subject",
"values": ["{\"id\": 23, \"name\":\"Joe\"}"]
},
{
"attribute": "Resource",
"values": ["account"]
}
]
}Learn more in Policy queries.
JSON PDP API response format
After the Policy Decision Service makes a decision, it returns the decision to the JSON PDP API, which then forwards the decision response to the client. JSON PDP API responses include decisions, such as PERMIT or DENY, and any obligations or statements that were matched during policy evaluation.
Individual response
The following example shows a valid response to an individual JSON request:
{
"id": "12345678-90ab-cdef-1234-567890abcdef",
"deploymentPackageId": "12345678-90ab-cdef-1234-567890abcdef",
"timestamp": "2021-06-11T03:12:19.720485Z",
"elapsedTime": 184024,
"decision": "PERMIT",
"authorized": true,
"statements": [
{
"id": "12345678-90ab-cdef-1234-567890abcdef",
"name": "Statement Name",
"code": "statement-code",
"payload": "{\"data\": \"some data\"}",
"obligatory": true,
"fulfilled": false,
"attributes": {}
}
],
"status": {
"code": "OKAY",
"messages": [],
"errors": []
}
}The decision and authorized values identify whether the policies authorize the request, and the statements array contains statements to be applied by the policy enforcement point.
|
|
Batch response
Batch responses are returned as an array named responses that contains individual JSON responses. The order of the responses matches the order of the original requests, meaning the first response in the responses array corresponds to the first request in the batch, the second response to the second request, and so on.
The following example shows a valid response to a batch JSON request:
{
"responses": [
{
"id": "12345678-90ab-cdef-1234-567890abcdef",
"deploymentPackageId": "12345678-90ab-cdef-1234-567890abcdef",
"timestamp": "2021-06-11T04:18:32.820482Z",
"elapsedTime": 830492,
"decision": "PERMIT",
"authorized": true,
"statements": [
{
"id": "12345678-90ab-cdef-1234-567890abcdef",
"name": "Advice Name",
"code": "advice-code",
"payload": "{\"data\": \"some data\"}",
"obligatory": true,
"fulfilled": false,
"attributes": {}
}
],
"status": {
"code": "OKAY",
"messages": [],
"errors": []
}
},
{
"id": "fedcba09-8765-4321-fedcba098765",
"deploymentPackageId": "fedcba09-8765-4321-fedcba098765",
"timestamp": "2021-06-11T04:18:33.650974Z",
"elapsedTime": 492048,
"decision": "PERMIT",
"authorized": true,
"statements": [
{
"id": "fedcba09-8765-4321-fedcba098765",
"name": "Different Advice",
"code": "advice-code",
"payload": "{\"data\": \"other data\"}",
"obligatory": false,
"fulfilled": false,
"attributes": {}
}
],
"status": {
"code": "OKAY",
"messages": [],
"errors": []
}
}
]
}|
|
Query response
The following example shows a valid response to a query request:
{
"requestId": "8245be35-ec9e-40f1-a79a-80890041f4b0",
"timeStamp": "2023-11-14T03:21:47.734842Z",
"elapsedTime": 22,
"results": [
{
"attribute": "action",
"value": "delete",
"decision": "PERMIT"
}
]
}The results array contains a list of query attribute values that either produced a PERMIT decision or a DENY decision, along with any obligations or statements that were matched.
|
|