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. For more information on the /query endpoint, see 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

JSON PDP API Endpoint path	Action	Content-Type/Accept	Request data
`/governance-engine`	POST	application/json	JSON
`/governance-engine/batch`	POST	application/json	JSON
`/governance-engine/query`	POST	application/json	JSON

/governance-engine

POST

application/json

JSON

/governance-engine/batch

POST

application/json

JSON

/governance-engine/query

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

Field	Type	Required	PingAuthorize Trust Framework type	Example value
`domain`	string	no	Domain	`Sales.Asia Pacific`
`action`	string	no	Action	`Retrieve`
`service`	string	no	Service	`Mobile.Landing page`
`identityProvider`	string	no	Identity Provider	`Social Networks.Spacebook`
`attributes`	map<string, string>	yes	Other Attributes	`\{"Prospect name": "B. Vo"}`

domain

string

Domain

Sales.Asia Pacific

action

string

Action

Retrieve

service

string

Service

Mobile.Landing page

identityProvider

string

Identity Provider

Social Networks.Spacebook

attributes

map<string, string>

yes

Other Attributes

\{"Prospect name": "B. Vo"}

Although the attributes value is required, you can leave it empty.

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.

Screen capture of the Attributes tab of the Trust Framework window in the Policy Editor. The Prospect name attribute is displayed configured as specified.

The Trust Framework attribute name must match with the key of the attributes map.

For example, if you have an attribute named "UserID", an example value for the "attributes" object would be {"UserID":13848}.

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"
	    }
        }
    ]
}

Query requests

Query requests differ from individual and batch JSON PDP API 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 values array empty in a query request sent in embedded policy decision point (PDP) mode. If you leave the values array empty in a request sent in external PDP mode, the relevant attribute is treated as an unbounded attribute.

The query array 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 PDP API request.

You can include single-valued attributes in the query or context fields. Including a single-valued attribute in the query field will add 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 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 statements 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": "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 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": [ ],
	  }
      }
    ]
}

Query response

The following example shows the correct query response format:

{
  "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 result or a DENY decision result with statements.