PingOne Advanced Identity Cloud API

REST API versions

To maintain compatibility between releases, many REST APIs are versioned (v1.0, v2.0, and so on). The version number of a feature increases when Advanced Identity Cloud introduces breaking changes to an API.

Advanced Identity Cloud provides versions for these API aspects:

resource

Any changes to the structure or syntax of a returned response result in a change to the resource version. For example, changing errorMessage to message in a JSON response.

protocol

Any changes to the methods used to make REST API calls result in change to the protocol version. For example, changing _action to $action in the required parameters of an API feature.

When an API is versioned, include resource versions in your REST calls by setting the Accept-API-Version request header. The following example requests resource version 2.0 and protocol version 1.0:

Accept-API-Version: resource=2.0, protocol=1.0

This header ensures you call the correct version of the API, avoiding unexpected behavior due to incompatible changes.

Always include resource versions in your REST calls. This ensures your applications remain compatible when Advanced Identity Cloud is updated.

Advanced Identity Cloud has cross-site request forgery (CSRF) protection for all the endpoints under /am/json. This protection requires all requests other than GET, HEAD, or OPTIONS to include one of the following headers:

  • Accept-API-Version

  • X-Requested-With

Specify versions

REST APIs use the Accept-API-Version header to specify protocol and resource versions:

Accept-API-Version: protocol=version,resource=version

protocol

The version reflects changes in the REST protocol, such as common method parameters and headers specified by the protocol itself, or the input or response conventions it prescribes.

For example, protocol version 2.2 introduced a _countOnly parameter.

resource

The version reflects changes in the resource implementation, including JSON representation of resources, input parameters required, and incompatible behavior changes.

For example, the version changes when errorMessage changes to message in a JSON response.

The following example requests resource version 2.0 and protocol version 1.0:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Secret12!" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'

Version messages

REST API responses include a content-api-version header to indicate the resource or protocol versions used to service the request. The following example shows a request for a version 2.0 resource and a response including a version 2.1 resource:

$ curl \
--request POST \
--include \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Secret12!" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
...
content-api-version: resource=2.1
...

When the request has an incomplete version specification or is missing the header, the response includes a warning header:

$ curl \
--request POST \
--include \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Secret12!" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
...
content-api-version: resource=2.1
warning: 100 OpenAM REST "No Accept-API-Version specified"
warning: 100 chf "Accept-API-Version should be included in the request."
...

If the version specification prevents Advanced Identity Cloud from serving the request, the response status is HTTP 404 Not Found and the response headers aren’t included:

$ curl \
--request POST \
--include \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Secret12!" \
--header "Accept-API-Version: resource=42.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
HTTP/2 404
...

In this error case, the response body is empty.