---
title: Authenticating to the JSON PDP API
description: The JSON PDP API can require a client to authenticate to it by using a shared secret.
component: pingauthorize
version: 11.0
page_id: pingauthorize:pingauthorize_server_administration_guide:paz_authenticate_json_pdp_api
canonical_url: https://docs.pingidentity.com/pingauthorize/11.0/pingauthorize_server_administration_guide/paz_authenticate_json_pdp_api.html
revdate: April 28, 2025
section_ids:
  json_create_shared_secret: Creating a shared secret
  steps: Steps
  example: Example:
  example-2: Example:
  json_delete_shared_secret: Deleting a shared secret
  steps-2: Steps
  example-3: Example:
  example-4: Example:
  rotating-shared-secrets: Rotating shared secrets
  steps-3: Steps
  customizing-the-shared-secret-header: Customizing the shared secret header
  steps-4: Steps
  example-5: Example:
---

# Authenticating to the JSON PDP API

The JSON PDP API can require a client to authenticate to it by using a shared secret.

To define shared secrets, use JSON PDP API Shared Secret configuration objects. To manage shared secrets, use the JSON PDP API HTTP Servlet Extension.

## Creating a shared secret

Define the authentication credentials that the JSON PDP API might require a client to present.

### Steps

1. To create a shared secret, run the following example `dsconfig` command, substituting values of your choosing.

   #### Example:

   ```
   PingAuthorize/bin/dsconfig create-authorization-policy-decision-shared-secret \
     --secret-name "Shared Secret A" \
     --set "shared-secret:secret123"
   ```

   |   |                                                                                                                                                                                                                                                                                          |
   | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | * The `shared-secret` property sets the value that the JSON PDP API requires the client to present. After you set this value, it is no longer visible.

   * The `secret-name` property is a label that allows an administrator to distinguish one JSON PDP API Shared Secret from another. |

2. To update the `shared-secrets` property, run the following example `dsconfig` command.

   #### Example:

   ```
   PingAuthorize/bin/dsconfig set-http-servlet-extension-prop \
     --extension-name "JSON PDP API" \
     --add "shared-secrets:Shared Secret A"
   ```

   A new JSON PDP API Shared Secret is not used until the `shared-secrets` property of the JSON PDP API HTTP Servlet Extension is updated.

## Deleting a shared secret

You can remove a shared secret from use or delete it entirely.

### Steps

* To remove a JSON PDP API Shared Secret from use, run the following example `dsconfig` command, substituting values of your choosing.

  #### Example:

  ```json
  {pingauthorize}/bin/dsconfig set-http-servlet-extension-prop \
    --extension-name "JSON PDP API" \
    --remove "shared-secrets:Shared Secret A"
  ```

* To delete a JSON PDP API Shared Secret, run the following example `dsconfig` command.

  #### Example:

  ```json
  {pingauthorize}/bin/dsconfig delete-authorization-policy-decision-shared-secret \
    --secret-name "Shared Secret A"
  ```

## Rotating shared secrets

To avoid service interruptions, the JSON PDP API allows multiple, distinct shared secrets to be accepted at the same time.

You can configure a new shared secret that the JSON PDP API accepts alongside an existing shared secret. This allows time to update the client to use the new shared secret.

### Steps

1. Create a new JSON PDP API shared secret and assign it to the JSON PDP API HTTP Servlet Extension. Learn more in [Creating a shared secret](#json_create_shared_secret).

2. Update the client to use the new shared secret.

3. Remove the previous JSON PDP API shared secret. Learn more in [Deleting a shared secret](#json_delete_shared_secret).

## Customizing the shared secret header

By default, the JSON PDP API accepts a shared secret from a client through the CLIENT-TOKEN header.

### Steps

* To customize a shared secret header, change the value of the JSON PDP API HTTP Servlet Extension's `shared-secret-header` property.

  #### Example:

  The following command changes the shared secret header to `x-shared-secret`.

  ```json
  {pingauthorize}/bin/dsconfig set-http-servlet-extension-prop \
    --extension-name "JSON PDP API" \
    --set shared-secret-header-name:x-shared-secret
  ```

  The following command resets the shared secret header to its default value.

  ```json
  {pingauthorize}/bin/dsconfig set-http-servlet-extension-prop \
    --extension-name "JSON PDP API" \
    --reset shared-secret-header-name
  ```