---
title: Sideband API authentication
description: Authenticate to the Sideband API by using a shared secret. Use the Sideband API HTTP Servlet Extension to manage shared secrets.
component: pingauthorize
version: 11.0
page_id: pingauthorize:pingauthorize_server_administration_guide:paz_authn_sideband_api
canonical_url: https://docs.pingidentity.com/pingauthorize/11.0/pingauthorize_server_administration_guide/paz_authn_sideband_api.html
revdate: March 30, 2026
section_ids:
  create_sideband_shared_secret: Creating a shared secret
  steps: Steps
  example: Example:
  example-2: Example:
  delete_sideband_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:
---

# Sideband API authentication

The Sideband API can require an API gateway plugin to authenticate to it by using a shared secret.

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

## Creating a shared secret

Define the authentication credentials that the Sideband API might require an API gateway plugin to present.

### Steps

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

   #### Example:

   ```json
   {pingauthorize}/bin/dsconfig create-sideband-api-shared-secret \
     --secret-name "Shared Secret A" \
     --set "shared-secret:secret123"
   ```

   |   |                                                                                                                                                                                                                                                                                                      |
   | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | * The `shared-secret` property sets the value that the Sideband API requires the API gateway plugin 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 Sideband API Shared Secret from another. |

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

   #### Example:

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

   A new Sideband API Shared Secret is not used until the `shared-secrets` property of the Sideband 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 Sideband 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 "Sideband API" \
    --remove "shared-secrets:Shared Secret A"
  ```

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

  #### Example:

  ```json
  {pingauthorize}/bin/dsconfig delete-sideband-api-shared-secret \
    --secret-name "Shared Secret A"
  ```

## Rotating shared secrets

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

You can configure a new shared secret that the Sideband API accepts alongside an existing shared secret. This allows time to update the API gateway plugin to use the new shared secret.

### Steps

1. Create a new Sideband API Shared Secret and assign it to the Sideband API HTTP Servlet Extension. Learn more in [Creating a shared secret](#create_sideband_shared_secret).

2. Update the API gateway plugin to use the new shared secret.

3. Remove the previous Sideband API Shared Secret. Learn more in [Deleting a shared secret](#delete_sideband_shared_secret).

## Customizing the shared secret header

By default, the Sideband API accepts a shared secret from an API gateway plugin through the CLIENT-TOKEN header.

### Steps

* To customize a shared secret header, change the value of the Sideband 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 "Sideband 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 "Sideband API" \
    --reset shared-secret-header-name
  ```