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 both an individual decision request endpoint and a batch request endpoint that consuming application servers can access using POST requests to the /governance-engine or /governance-engine/batch paths, respectively.
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 |
application/json |
JSON |
|
POST |
application/json |
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 advice. See the JSON PDP API Reference for more information about making API requests. |
JSON PDP API request format
Individual requests
A valid JSON PDP API request is a simple JSON object that can be forwarded to the Policy Decision Service. Policies can match a decision request by Service, Domain, Action, or other attributes.
The following table describes the values contained in a valid JSON PDP API request.
| Field | Type | Required | PingAuthorize Trust Framework type | Example value |
|---|---|---|---|---|
|
string |
no |
Domain |
|
|
string |
no |
Action |
|
|
string |
no |
Service |
|
|
string |
no |
Identity Provider |
|
|
map<string, string> |
yes |
Other Attributes |
|
|
While the |
The following example shows the correct format of a JSON individual decision 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 Administration GUI. In this example, the Prospect name attribute has a Request resolver and a Value Settings type of string.
|
The Trust Framework attribute name must match with the key of the attributes map. For example, if you have an attribute named |
Batch requests
Batch requests consist of an array named "requests" of JSON objects, each of which is a standard JSON PDP API single decision request.
The following example shows the correct format of a JSON batch decision 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"
}
}
]
}JSON PDP API response format
After the Policy Decision Service determines a decision response, it hands the response back to the JSON PDP API to provide to the client. JSON PDP API responses include decisions, such as Permit or Deny, and any obligations or advice that matched during policy processing.
Individual response
The following example shows the correct JSON individual response format.
{
"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": "Advice Name",
"code": "advice-code",
"payload": "{\"data\": \"some data\"}",
"obligatory": true,
"fulfilled": false,
"attributes": { }
}
],
"status": {
"code": "OKAY",
"messages": [ ],
"errors": [ ],
}
}|
The |
Batch response
Batch decision responses consist of an array, named "responses", of JSON objects, each of which is a standard JSON PDP API single decision response. The decision responses are guaranteed to be returned in the same order as the received responses. For example, the first response in the batch responses corresponds to a decision on the first request in the batch requests.
The following example shows the correct JSON batch decision response format.
{
"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": [ ],
}
}
]
}