PingOne Platform APIs

External transaction and session IDs

In order to help track transactions, the PingOne platform supports the following custom HTTP headers across all endpoints:

  • X-Ping-External-Transaction-Id

    Represents a scope larger than a single PingOne API request. It identifies one transaction that encompasses multiple API requests to PingOne.

  • X-Ping-External-Session-Id

    Represents a scope larger than a single transaction. It identifies multiple transactions in the context of a session. For example, an end user completed an authentication request and several transactions one hour ago and now needs to re-authenticate. The session should be the same.

The X-Ping-External-Transaction-Id and X-Ping-External-Session-Id headers are custom headers defined by PingOne. They are useful for tracking purposes, but they have no broader meaning outside their usage in PingOne. The values associated with these headers are not checked against any external source.

You can pass these optional headers to PingOne products to correlate with your own transactions and sessions. In an audit record produced by an API request with either (or both) of these headers, the audit report includes them as translated properties. For example, the following request to update an environment includes these headers.

curl --location --request PUT '{{apiPath}}/environments/{{envID}}' \
--header 'Accept: */*' \
--header 'X-Ping-External-Transaction-Id: 123456' \
--header 'X-Ping-External-Session-Id: 987654' \
--header 'Authorization: ••••••' \
--data '{
    "name": "Updated-Environment-Name"
}'

The response for a GET {{apiPath}}/environments/{{envID}}/activities/{{activityID}} audit request that identifies this activity returns the values specified in these headers as externalCorrelation properties.

{
  "_links": {
    "self": {
      "href": "{{apiPath}}/environments/{{envID}}/activities/{{activityID}}"
    }
  },
  "id": "{{activityID}}",
  "recordedAt": "2025-02-11T00:05:42.008Z",
  "createdAt": "2025-02-11T00:05:42.028Z",
  "correlationId": "96a77998-5b46-43af-b00f-d7efb2f811c2",
  "externalCorrelation": {
    "transactionId": "123456",
    "sessionId": "987654"
  },

Custom header validation rules

PingOne validates all custom HTTP headers.

  • The maximum length of the header is 100 characters. If exceeded, the header will be truncated to 100 characters.

  • Any invalid characters will be converted to underscores. The following characters are allowed:

    • Unicode letters, combining marks, numeric characters, dots, underscores, dashes

    • /, @, =, #, ``