--- title: JSON PDP API request and response flow description: The JSON policy decision point API provides a REST API for attribute-based access control based on policies configured in the Policy Decision Service. component: pingauthorize version: 10.2 page_id: pingauthorize:pingauthorize_server_administration_guide:paz_json_pdp_api_flow canonical_url: https://docs.pingidentity.com/pingauthorize/11.1/pingauthorize_server_administration_guide/paz_json_pdp_api_flow.html llms_txt: https://docs.pingidentity.com/pingauthorize/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: January 23, 2026 superseded_by: https://docs.pingidentity.com/pingauthorize/11.1/pingauthorize_server_administration_guide/paz_json_pdp_api_flow.html section_ids: request-and-response-flow: Request and response flow json-pdp-api-request-format: JSON PDP API request format individual_json_request: Individual requests json_pdp_batch_requests: Batch requests query_request_format: Query requests json_pdp_response: JSON PDP API response format individual-responses: Individual responses batch-responses: Batch responses query-response: Query response config_response_timestamp_precision: Configuring response timestamp precision --- # 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](paz_config_policy_decision_svc.html). Client applications can use this API to request authorization decisions in individual, query, or batch modes. Each request type corresponds to a specific endpoint: | Endpoint path | Method | Content-Type/Accept | Request body | | -------------------------- | ------ | ------------------- | ------------ | | `/governance-engine` | POST | `application/json` | JSON | | `/governance-engine/batch` | POST | `application/json` | JSON | | `/governance-engine/query` | POST | `application/json` | JSON | All requests must include valid JSON bodies in the expected format and specify the appropriate HTTP headers: ``` Content-Type: application/json Accept: application/json ``` ## Request and response flow A successful JSON PDP API request goes through the following flow: Sequence diagram of the JSON PDP API request and response flow 1. The client sends a JSON decision request to one of the PDP API endpoints. 2. The JSON PDP API forwards the request to the Policy Decision Service. 3. The Policy Decision Service evaluates the request according to the configured policies and returns a decision. 4. The JSON PDP API sends the decision response back to the client. 5. The policy enforcement point (PEP) applies any obligations or statements returned in the response. Learn more about making JSON PDP API requests in the [JSON PDP API Reference](https://developer.pingidentity.com/pingauthorize/pingauthorize/policy-decision/json-pdp.html) documentation. ## 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 | Trust Framework type | Example value | | ------------------ | --------------------- | -------- | -------------------- | ---------------------------- | | `domain` | String | Optional | Domain | `Sales.Asia Pacific` | | `action` | String | Optional | Action | `Retrieve` | | `service` | String | Optional | Service | `Mobile.​Landing page` | | `identityProvider` | String | Optional | Identity Provider | `Social Networks.​Spacebook` | | `attributes` | Map \ | Required | Other Attributes | `{"Prospect name": "B. Vo"}` | | | | | - | ------------------------------------ | | | The `attributes` field can be empty. | Example ```json { "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. ![Screen capture of the Attributes tab of the Trust Framework window in the Policy Editor. The Prospect name attribute is displayed configured as specified.](_images/azw1585224511059.png) | | | | - | ------------------------------------------------------------------------------ | | | The Trust Framework attribute name must match the key of the `attributes` map. | ### Batch requests Batch requests consist of a `requests` array that contains individual JSON requests. Example ```json { "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**: Attributes without specified values. Their values can be resolved at decision runtime by calling external services or referencing other query attributes. You must enable and configure query settings for unbounded attributes. Learn more in [Enabling query settings](../pingauthorize_policy_administration_guide/paz_enabling_query_settings.html). * **Multivalued**: Attributes with multiple values specified. A query request includes the following fields: * `query`: An array containing the following elements: * `attribute`: The full name of an unbounded, multivalued, or standard authorization attribute. * `values` (optional): An array defining the values of the attribute. If multiple values are included, the attribute is treated as multivalued. If the attribute is unbounded, omit this field. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You cannot leave the `values` array empty in [embedded policy decision point (PDP)](paz_config_embedded_pdp.html) mode. In [external PDP mode](paz_config_external_pdp.html), attributes with an empty `values` array are treated as unbounded. | 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 same fields as a standard [individual JSON request](#individual_json_request). You can include single-valued attributes in either the `query` or `context` fields. When a single-valued attribute is included in `query`, it appears in each element of the `results` array in the response. The following example asks which actions Joe can perform on the account: Example ```json { "query": [ { "attribute": "action" }, { "attribute": "Subject", "values": ["{\"id\": 23, \"name\":\"Joe\"}"] }, { "attribute": "Resource", "values": ["account"] } ] } ``` Learn more in [Policy queries](../pingauthorize_policy_administration_guide/paz_policy_queries.html). ## 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 responses The following example shows a response to an individual JSON request: ```json { "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 PEP. The `elapsedTime` value shows evaluation duration in microseconds. ### Batch responses Batch responses are returned as a `responses` array 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 response to a batch JSON request: ```json { "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 response to a query request: ```json { "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. ### Configuring response timestamp precision The PingAuthorize Server includes a timestamp in each JSON PDP API response indicating when the policy decision was produced. By default, PingAuthorize uses the highest timestamp precision available on the host's operating system and CPU. For example, on hosts that support nanosecond timestamps, responses include nanosecond-precision values. On hosts that only support a lower precision, such as microseconds, PingAuthorize uses that precision instead. You can enforce microsecond-precision timestamps to maintain compatibility with clients that expect legacy formats. To enable this behavior, set the Policy Decision Service property `use-microseconds-timestamp` to `true`: ``` dsconfig set-policy-decision-service-prop \ --set use-microseconds-timestamp:true ``` To revert to the highest available precision: ``` dsconfig set-policy-decision-service-prop \ --reset use-microseconds-timestamp ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------- | | | This setting affects the API response body only. The `policy-decision` and `policy-query` log files continue using the default precision. |