--- title: XACML-JSON PDP API request and response flow description: The XACML-JSON policy decision point (PDP) API is a standards-based HTTP API used to make authorization decisions based on policies configured in the PingAuthorize Server Policy Decision Service. component: pingauthorize version: 11.0 page_id: pingauthorize:pingauthorize_server_administration_guide:paz_xacml_json_pdp_api_flow canonical_url: https://docs.pingidentity.com/pingauthorize/11.0/pingauthorize_server_administration_guide/paz_xacml_json_pdp_api_flow.html revdate: January 13, 2026 section_ids: requests: Requests authorization: Authorization decision-processing: Decision processing responses: Responses peer_recognition_example: Example --- # XACML-JSON PDP API request and response flow The XACML-JSON policy decision point (PDP) API is a standards-based HTTP API used to make authorization decisions based on policies configured in the PingAuthorize Server [Policy Decision Service](paz_config_embedded_pdp.html). The XACML-JSON PDP API is implemented as a single endpoint, which consuming application servers can access using POST requests to the `/pdp` path. The HTTP requests must include the appropriate `Content-Type` and `Accept` headers, and request bodies must adhere to the XACML-JSON standard. Learn more in [Requests](#requests). | XACML-JSON PDP API Endpoint path | Action | Content-Type/Accept | Request data | | -------------------------------- | ------ | ------------------------ | ------------ | | `/pdp` | POST | `application/xacml+json` | XACML-JSON | The XACML-JSON PDP API supports the [MultiRequests JSON object](https://docs.oasis-open.org/xacml/xacml-json-http/v1.1/csprd01/xacml-json-http-v1.1-csprd01.html#_Toc525043922), which allows a client to make multiple decision requests in a single HTTP request. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Because this object also supports single decision requests, it's the only supported XACML-JSON request format. Learn more about making XACML-JSON PDP API requests in the [XACML-JSON PDP API Reference](https://developer.pingidentity.com/pingauthorize/pingauthorize/policy-decision/xacml-json-pdp.html) documentation. | A successful XACML-JSON PDP API request goes through the following two-phase flow: 1. The client makes the XACML-JSON request, which is received by the XACML-JSON PDP API. The API converts the request to a PingAuthorize Server batch decision request and attempts to authorize the client. 2. When the client is successfully authorized, the request is handed off to the Policy Decision Service to process decisions in batch for the XACML-JSON PDP API. The API then converts the batch decision responses to a XACML-JSON response and writes the response to the client. Sequence diagram of the XACML-JSON PDP API request and response flow The following sections describe these stages in more detail. ## Requests The XACML-JSON PDP API first converts the XACML-JSON request to a batch decision request for the policy decision point to be consumed by the Policy Decision Service. Policies can match a decision request by `Service`, `Domain`, `Action`, or other attributes. The following example XACML-JSON request body illustrates the conversion to a batch decision request. For an example with more than one decision request, refer to [Example](#peer_recognition_example). ```json { "Request": { "MultiRequests": { "RequestReference": [{ "ReferenceId": [ "dom", "act", "srv", "idp", "att" ] }] }, "AccessSubject": [{ "Id": "dom", "Attribute": [{ "AttributeId": "domain", "Value": "Sales.Asia Pacific" }] }], "Action": [{ "Id": "act", "Attribute": [{ "AttributeId": "action", "Value": "Retrieve" }] }], "Resource": [{ "Id": "srv", "Attribute": [{ "AttributeId": "service", "Value": "Mobile.Landing page" }] }], "Environment": [{ "Id": "idp", "Attribute": [{ "AttributeId": "symphonic-idp", "Value": "Social networks.Spacebook" }] }], "Category": [{ "Id": "att", "Attribute": [{ "AttributeId": "attribute:Prospect name", "Value": "B. Vo" }] }] } } ``` The previous example shows a single decision request with the following attributes: * A domain of `Sales.Asia Pacific` * An action of `Retrieve` * A service of `Mobile.Landing page` * An identity provider of `Social networks.Spacebook` * A single attribute named `Prospect name`, with a value of `B. Vo` The following table shows how these values map from the Trust Framework entities to the XACML-JSON request. | Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type | Example value | | ------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------- | ---------------------------- | | `$.Request` | `$.AccessSubject[*].Attribute[?(@.AttributeId == "domain")].Value` | Domain | `Sales.Asia Pacific` | | | `$.Action[*].Attribute[?(@.AttributeId == "action")].Value` | Action | `Retrieve` | | | `$.Resource[*].Attribute[?(@.AttributeId == "service")].Value` | Service | `Mobile.​Landing page` | | | `$.Environment[*].Attribute[?(@.AttributeId == "symphonic-idp")].Value` | Identity Provider | `Social Networks.​Spacebook` | | | `$.Category[*].Attribute[?(@.AttributeId == "attribute:Prospect name")].Value` | Other Attribute (`Prospect name` in this case) | `B. Vo` | To illustrate how you can match rules against the `Prospect name` Trust Framework attribute, 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 **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.](_images/azw1585224511059.png) | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------- | | | The Trust Framework attribute name must be a case-sensitive match with the decision request `AttributeId` after the `attribute:` prefix is removed. | ## Authorization Before calculating a decision, the XACML-JSON PDP API attempts to authorize the client making the XACML-JSON PDP API request by invoking the Policy Decision Service. A PDP authorization request can be targeted in policy as having service PDP with action authorize. The default policies included with PingAuthorize Server perform this authorization by only permitting requests with active access tokens that contain the `urn:pingauthorize:pdp` scope. You can see this policy in **Global Decision Point → PDP API Endpoint Policies → Token Authorization**. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | | The parent of the Token Authorization policy, PDP API Endpoint Policies, constrains the Token Authorization policy to apply to the PDP service only. | For example, under the default policies, the following request would result in an authorized client when the PDP is configured with a mock access token validator. ```shell curl --insecure -X POST \ -H 'Authorization: Bearer {"active":true,"scope":"urn:pingauthorize:pdp", "sub":""}' \ -H 'Content-Type: application/xacml+json' \ -d '{"Request":{}}' "https://:/pdp" ``` The default policies are intended to provide a foundation. You can modify these policies if additional authorization logic is required. ## Decision processing On successful client authorization, the XACML-JSON PDP API invokes the Policy Decision Service with the batch decision requests converted from the XACML-JSON request. When writing policy for the XACML-JSON PDP API endpoint, you should note the mapping between the XACML-JSON schema and the PingAuthorize Server decision request. Learn more in [Requests](#requests). After the Policy Decision Service determines a decision response, it forwards the response back to the XACML-JSON PDP API to provide to the client. ## Responses The XACML-JSON PDP API converts batch decision responses to a XACML-JSON response. XACML-JSON responses include decisions, such as `Permit` or `Deny`, and any obligations or advice that matched during policy processing. | | | | - | ------------------------------------------------------------------------ | | | The Policy Enforcement Point (PEP) must apply any obligations or advice. | The following table shows the mapping from a decision response to a XACML-JSON response. | Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type | | ---------------------------------- | ------------------------------------------------------------ | ---------------------------------- | | `$.Response[*]` | `$.Decision` | Decision | | `$.Response[].​Obligations[]` | ` `` ` | Advice (obligatory) | | | `$.Id` | Advice code | | | `$.AttributeAssigments[?(@.AttributeId == "payload")].Value` | Advice payload | | `$.Response[].​AssociatedAdvice[]` | | Advice (non-obligatory) | | | `$.Id` | Advice code | | | `$.AttributeAssigments[?(@.AttributeId == "payload")].Value` | Advice payload | The following example is an appropriate response based on the request in [Requests](#requests). ```json { "Response": [{ "Decision": "Permit", "Obligations": [{ "Id": "obligation-id", "AttributeAssignments": [{ "AttributeId": "payload", "Value": "payload-value" }] }], "AssociatedAdvice": [{ "Id": "advice-id", "AttributeAssignments": [{ "AttributeId": "payload", "Value": "payload-value" }] }] }] } ``` In this example, it is up to the application server to handle the obligations and advice in the response. ## Example This example shows how to use the XACML-JSON PDP API in the context of a peer recognition program. The example company, AnyCompany, has an internal peer recognition program. The peer recognition program allows employees to recognize each other by awarding each other points. The points can be spent in different categories. Each category requires a minimum number of points for the category to become available. When an employee spends enough points in a category, a related product becomes unlocked in an online catalog that the employee can purchase. AnyCompany has implemented a web application where employees spend their points, view their available catalog, and purchase products. In this example, the web application that implements the online catalog can make the following XACML-JSON request when an employee spends their points. The request includes three decision requests. ```json { "Request":{ "MultiRequests":{ "RequestReference":[ { "ReferenceId":[ "domain-1", "action-1", "service-1", "idp-1", "attributes-1" ] }, { "ReferenceId":[ "domain-1", "action-2", "service-2", "idp-1", "attributes-2" ] }, { "ReferenceId":[ "domain-1", "action-1", "service-3", "idp-1", "attributes-1" ] } ] }, "AccessSubject":[ { "Id":"domain-1", "Attribute":[ { "AttributeId":"domain", "Value":"AnyCompany.Management" } ] } ], "Action":[ { "Id":"action-1", "Attribute":[ { "AttributeId":"action", "Value":"Update" } ] }, { "Id":"action-2", "Attribute":[ { "AttributeId":"action", "Value":"Retrieve" } ] } ], "Resource":[ { "Id":"service-1", "Attribute":[ { "AttributeId":"service", "Value":"Peer Recognition.Point allocation" } ] }, { "Id":"service-2", "Attribute":[ { "AttributeId":"service", "Value":"Peer Recognition.Points unspent" } ] }, { "Id":"service-3", "Attribute":[ { "AttributeId":"service", "Value":"Peer Recognition.Products" } ] } ], "Category":[ { "Id":"attributes-1", "Attribute":[ { "AttributeId":"attribute:User input.User Id", "Value":"self" }, { "AttributeId":"attribute:User input.Entertainment", "Value":8 }, { "AttributeId":"attribute:User input.Travel", "Value":5 }, { "AttributeId":"attribute:User input.Academics", "Value":6 }, { "AttributeId":"attribute:User input.Electronics", "Value":5 }, { "AttributeId":"attribute:User input.Sports", "Value":5 }, { "AttributeId":"attribute:User input.Food", "Value":7 }, { "AttributeId":"attribute:User input.Music", "Value":4 } ] }, { "Id":"attributes-2", "Attribute":[ { "AttributeId":"attribute:User input.User Id", "Value":"self" } ] } ], "Environment":[ { "Id":"idp-1", "Attribute":[ { "AttributeId":"symphonic-idp", "Value":"AnyCompany SSO" } ] } ] } } ``` The three decision requests are summarized in the `RequestReference` JSON array. Each JSON object in the array contains a single field, `ReferenceId`. Each `ReferenceId` field contains an array of `Id` references that represent the content of the decision request. The following tables highlight the key components of each decision request. | | | | - | ----------------------------------------------------------------------------------- | | | For brevity, only one Trust Framework attribute is listed in each decision request. | **First decision request** | Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type | Example value | | ----------------------------- | ----------------------------------------------------------------------- | ---------------------------------- | ----------------------------------- | | `$.Request.​AccessSubject[*]` | `$.Attribute[?(@.AttributeId == "domain")].Value` | Domain | `AnyCompany.​Management` | | `$.Request.​Action[*]` | `$.Attribute[?(@.AttributeId == "action")].Value` | Action | `Update` | | `$.Request.​Resource[*]` | `$.Attribute[?(@.AttributeId == "service")].Value` | Service | `Peer Recognition.Point allocation` | | `$.Request.​Environment[*]` | `$.Attribute[?(@.AttributeId == "symphonic-idp")].Value` | Identity Provider | `AnyCompany SSO` | | `$.Request.​Category[*]` | `$.Attribute[?(@.AttributeId == "attribute:User input.Entertainment")]` | Attribute | `8` | **Second decision request** | Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type | Example value | | ----------------------------- | ----------------------------------------------------------------- | ---------------------------------- | --------------------------------- | | `$.Request.​AccessSubject[*]` | `$.Attribute[?(@.AttributeId == "domain")].Value` | Domain | `AnyCompany.​Management` | | `$.Request.​Action[*]` | `$.Attribute[?(@.AttributeId == "action")].Value` | Action | `Retrieve` | | `$.Request.​Resource[*]` | `$.Attribute[?(@.AttributeId == "service")].Value` | Service | `Peer Recognition.Points unspent` | | `$.Request.​Environment[*]` | `$.Attribute[?(@.AttributeId == "symphonic-idp")].Value` | Identity Provider | `AnyCompany SSO` | | `$.Request.​Category[*]` | `$.Attribute[?(@.AttributeId == "attribute:User input.User Id")]` | Attribute | `self` | **Third decision request** | Parent (JSON Path) | Field (JSON Path) | PingAuthorize Trust Framework type | Example value | | ----------------------------- | ---------------------------------------------------------------- | ---------------------------------- | --------------------------- | | `$.Request.​AccessSubject[*]` | `$.Attribute[?(@.AttributeId == "domain")].Value` | Domain | `AnyCompany.​Management` | | `$.Request.​Action[*]` | `$.Attribute[?(@.AttributeId == "action")].Value` | Action | `Retrieve` | | `$.Request.​Resource[*]` | `$.Attribute[?(@.AttributeId == "service")].Value` | Service | `Peer Recognition.Products` | | `$.Request.​Environment[*]` | `$.Attribute[?(@.AttributeId == "symphonic-idp")].Value` | Identity Provider | `AnyCompany SSO` | | `$.Request.​Category[*]` | `$.Attribute[?(@.AttributeId == "attribute:User input.Travel")]` | Attribute | `5` | The following is an example response to the previous example request. The XACML-JSON response contains the decision responses for each of the three decision requests. The order of the decision responses corresponds to the order of the decision requests. In the first decision response, the system policy does not detect any problems and permits the employee to change her point allocation. In the second decision response, the system policy allows the employee to view her own unspent points and indicates that the value is now 0. In the third decision response, the system permits the retrieval of the employee's own product catalog and indicates which of the products should be unlocked for purchase. Given the response, the web application can now render the content for the three decision requests. It renders the 0 unspent points and all catalog products, with purchase buttons disabled where appropriate. ```json { "Response": [ { "Decision": "Permit", "Obligations": [], "AssociatedAdvice": [] }, { "Decision": "Permit", "Obligations": [], "AssociatedAdvice": [{ "Id": "remaining-points", "AttributeAssignments": [{ "AttributeId": "payload", "Value": "0" }] }] }, { "Decision": "Permit", "Obligations": [], "AssociatedAdvice": [{ "Id": "catalog", "AttributeAssignments": [{ "AttributeId": "attribute:Derived.Product availability.Trip to exotic country", "Value": "false" }, { "AttributeId": "attribute:Derived.Product availability.Super Bowl tickets", "Value": "false" }, { "AttributeId": "attribute:Derived.Product availability.Movie theater gift card", "Value": "true" }, { "AttributeId": "attribute:Derived.Product availability.Encyclopedia subscription", "Value": "false" }, { "AttributeId": "attribute:Derived.Product availability.Dinner at 5-star restaurant", "Value": "true" }, { "AttributeId": "attribute:Derived.Product availability.Expensive laptop", "Value": "false" }, { "AttributeId": "payload", "Value": "2020-03-17T16:21:20.175132-05:00" }] }] }] } ```