---
title: Configuring policy request header mappings
description: Configure the PingAuthorize server to enforce policy request header mappings on JSON PDP API requests.
component: pingauthorize
version: 11.0
page_id: pingauthorize:pingauthorize_server_administration_guide:paz_policy_request_header_mappings
canonical_url: https://docs.pingidentity.com/pingauthorize/11.0/pingauthorize_server_administration_guide/paz_policy_request_header_mappings.html
revdate: December 4, 2025
section_ids:
  steps: Steps
  configuring-policy-request-header-mappings-using-dsconfig: Configuring policy request header mappings using dsconfig
  steps-2: Steps
  example: Example
---

# Configuring policy request header mappings

With the Policy Decision Service set to [embedded policy decision point](paz_config_embedded_pdp.html) (PDP) mode, you can configure the PingAuthorize Server to apply policy request header mappings to [JSON PDP API](paz_json_pdp_api_flow.html) requests.

By defining a policy request header mapping, you can map a decision request header to a Trust Framework attribute. The PingAuthorize Server uses this mapping to dynamically populate the attribute's value with the value of an incoming request header, enabling policies to use header data in making authorization decisions. In embedded PDP mode, the PingAuthorize server only applies these mappings to individual (`/governance-engine`) and batch (`/governance-engine/batch`) JSON PDP API requests.

Header mappings support both single-valued and multivalued headers.

* You can define multivalued headers with either comma-separated values or duplicate header names.

  The Policy Decision Service treats comma-separated values as a single string.

* If there are duplicate header names with different values, the Policy Decision Service uses the first value specified in the request.

If multiple header names map to the same attribute, the Policy Decision Service uses the value of the header that appears last in the PingAuthorize admin console's alphabetically ordered list, as shown below:

![Screen capture of the Policy Request Header Mappings list in the PingAuthorize admin console](_images/paz_request_header_mappings_list.png)

|   |                                                                                                                                                                      |
| - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | If a decision request includes different values for a mapped header and attribute, the Policy Decision Service overwrites the attribute value with the header value. |

You can also configure policy request header mappings when developing and testing policies in the Policy Editor. Learn more in [Configuring Policy Editor policy request header mappings](paz_config_pe_request_header_mapping.html).

* Admin console

* dsconfig

### Steps

1. Go to **Configuration > Authorization and Policies > Policy Decision Service**.

2. In the **Policy Request Header Mappings** section, click **New Policy Request Header Mapping**.

3. In the **Name** field, enter the name of the header.

   |   |                                               |
   | - | --------------------------------------------- |
   |   | The request header name isn't case-sensitive. |

4. In the **Attribute Name** field, enter the full name of the attribute that you want to map to the relevant header.

   ![Screen capture of the New Policy Request Header Mapping page, with sample values included in the Name and Attribute Name fields](_images/paz_new_policy_request_header_mapping.png)

   |   |                                                                                                                                                                                                                                                                                                                                                                                    |
   | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | The full name of an attribute represents that attribute's full path in the Trust Framework hierarchy. For example, a **Param1** attribute with parent attributes **Request** and **Header** would have a full name of **Request.Header.Param1**.To quickly obtain an attribute's full name, click the hamburger menu of that attribute and select **Copy full name to clipboard**. |

5. Click **Save**.

## Configuring policy request header mappings using `dsconfig`

### Steps

* To create a new policy request header mapping, use the `dsconfig create-policy-request-header-mapping` command and supply the `mapping-name` and `set attribute-name` arguments.

  ```
  dsconfig create-policy-request-header-mapping \
  --mapping-name x-param-1 \
  --set attribute-name: Request.Header.param1
  ```

  The `mapping-name` should match the name of the request header, and the `attribute-name` should match the full name of the attribute defined in the Trust Framework.

  |   |                                                                                                                                                                                                                                                                                                                                                                                    |
  | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  |   | The full name of an attribute represents that attribute's full path in the Trust Framework hierarchy. For example, a **Param1** attribute with parent attributes **Request** and **Header** would have a full name of **Request.Header.Param1**.To quickly obtain an attribute's full name, click the hamburger menu of that attribute and select **Copy full name to clipboard**. |

## Example

Suppose you want to add a request correlation ID so that your logging and monitoring services have full visibility of a decision request's processing journey. This correlation ID is represented by the **x-correlation-id** authorization attribute, which has a parent **Request** attribute. The following policy request header mapping creates a mapping between the `x-correlation-id` header and the **x-correlation-id** attribute:

![Screen capture of the New Policy Request Header Mapping page with an example x-correlation-id mapping defined](_images/paz_correlation_id_header_mapping.png)

To include the modified decision request body in the JSON PDP API response, select the **Request** checkbox under [Decision Response View](paz_config_decision_response_view.html).

![Screen capture of the Decision Response View in the Policy Request Configuration section of the admin console, with the request view selected](_images/paz_header_mappings_decision_response_view.png)

|   |                                                                                                                                                                                                 |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Selecting the **Request** view causes the [Policy Decision Logger](paz_enable_detailed_logging.html#policy_decision_logger) to record potentially sensitive data in API requests and responses. |

Suppose a decision request includes a sample **Attribute1** attribute and a header value of `x-correlation-id:abc`. The relevant authorization policy produces a `PERMIT` decision if the **Request.x-correlation-id** attribute equals `"abc"` and a `DENY` decision otherwise:

```json
{
  "domain": "example.Domain",
  "action": "example.Action",
  "service": "example.Service",
  "identityProvider": "example.Identity Provider",
  "attributes": {
    "Attribute1": "A request body attribute"
  }
}
```

The following decision response includes the modified request body, which now includes the `Request.x-correlation-id` attribute set to the `x-correlation-id` header's value:

```json
{
  "id": "18e98969-3915-4096-b437-71100ac1d70f",
  "deploymentPackageId": "502bdfdf-da19-47c9-b474-0047f77d18de",
  "timestamp": "2024-05-23T15:29:30.115879Z",
  "elapsedTime": 193449,
  "request": {
    "domain": "example.Domain",
    "service": "example.Service",
    "action": "example.Action",
    "attributes": {
      "Attribute1": "A request body attribute",
      "Request.x-correlation-id": "abc"
    }
  },
  "decision": "PERMIT",
  "authorised": true,
  "statements": [],
  "status": {
  "code": "OKAY",
  "messages": [],
  "errors": []
  }
}
```