API responses

HTTP response headers

The PingOne API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body.

The following HTTP Headers are returned by every operation:

Access-Control-Allow-Headers

Used in response to a cross-origin resource sharing (CORS) preflight request to indicate the HTTP headers that can be used when making a request.
Access-Control-Allow-Max-Age

Specifies how long the results of a CORS preflight request can be cached.
Access-Control-Allow-Methods

Specifies the method or methods allowed when accessing the resource in response to a CORS preflight request.
Cache-Control

Specifies directives for caching mechanisms in both requests and responses.
Content-Type

Specifies the data exchange format for the response data.
Correlation-Id

A custom header.
Date

Shows the date the response was sent.
Expires

Shows the date and time when the response expires.
Pragma

Used for backwards compatibility with HTTP/1.0 caches in which the Cache-Control HTTP/1.1 header is not yet present.
Strict-Transport-Security

Allows a web site to tell browsers that the site should only be accessed using HTTPS, instead of HTTP.
Transfer-Encoding

Specifies the form of encoding used to safely transfer the entity to the user.
Vary

Determines how to match future request headers to decide whether a cached response can be used rather than requesting a fresh one from the origin server. It is used by the server to indicate which headers it used when selecting a representation of a resource in a content negotiation algorithm.
Via

Used for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of senders along the request/response chain.
X-Content-Type-Options

A marker used by the server to indicate that the MIME types advertised in the Content-Type headers should not be changed and be followed.
X-Frame-Options

This denies rendering in a frame where there is a frame mismatch.
X-XSS-Protection

A feature of Internet Explorer, Chrome, and Safari that stops pages from loading when the browsers detect reflected cross-site scripting (XSS) attacks.

HTTP response codes

The PingOne API returns the status of an operation as a registered HTTP response code. The HTTP response codes can be summarized as:

200-299

Confirms a successful call.
300-399

Indicates that the call or subsequent calls should be made to another resource.
400-499

Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters.
500-599

Shows that an error occurred, generally due to an issue with the service (for example, a service outage).

Operations can also return additional information about a failed operation in the HTTP response body.

Synchronous responses

Responses for synchronous operations have the following behavior:

GET operations

A request that returns a body also returns the code 200 OK with the resource in the body of the response.
POST operations

A request that creates a new resource returns 201 CREATED with a Location header containing the location of the created resource.
PUT or PATCH operations

A request that updates a resource returns 200 OK and the full resource in the body.
DELETE operations

A request that deletes a resource returns 204 NO CONTENT.

Asynchronous responses

The PingOne API can create a long-running or asynchronous operation that can be monitored by a client. An asynchronous operation will have the following behavior:

POST operations

Responses include 202 ACCEPTED with a Location header containing the location of the newly created operation. The client can poll the provided location to check the status of the operation. The operation may also return a suggested number of seconds for the client to recheck the status using the Retry-After HTTP header.
Canceling long-running operations

Some resources may allow the client to cancel an operation by performing a DELETE request on the created resource.
Clean up

The PingOne API will clean up operation history according to the application requirements (such as, keep the last n results, or purge results after the client has verified its success).

Response data structure

HAL (Hypertext Application Language) is a formatting convention that provides hyperlinks to related resources returned by an API request. For example, a GET /environments/{{envID}}/users/{{userID}} request returns data for a specific user resource. The _links object in the JSON response data shows the hyperlinks to related resources associated with this user. You can use the roleAssignments link to get role assignments associated with this user, or the password.reset link to perform password management actions on this user resource.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c"
        },
        "population": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/populations/60971d3b-cc5a-4601-9c44-2be541f91bf1"
        },
        "devices": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/devices"
        },
        "roleAssignments": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/roleAssignments"
        },
        "password": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
        },
        "password.check": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
        },
        "linkedAccounts": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/linkedAccounts"
        },
        "account.sendVerificationCode": {
            "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab"
        }
    },
    "_embedded": {
        "password": {
            "status": "PASSWORD_EXPIRED"
        },
        "population": {
            "_links": {
                "self": {
                    "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/populations/60971d3b-cc5a-4601-9c44-2be541f91bf1"
                },
                "environment": {
                    "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c"
                }
            },
            "id": "60971d3b-cc5a-4601-9c44-2be541f91bf1"
        }
    },
    "id": "8376797d-641c-4e7b-8bc1-2fdf71916cab",
    "environment": {
        "id": "5caa81af-ec05-41ff-a709-c7378007a99c"
    },
    "createdAt": "2020-02-18T20:50:14.092Z",
    "email": "tomjones@example.com",
    "enabled": true,
    "lifecycle": {
        "status": "ACCOUNT_OK"
    },
    "mfaEnabled": false,
    "name": {
        "given": "Tom",
        "family": "Jones"
    },
    "population": {
        "id": "60971d3b-cc5a-4601-9c44-2be541f91bf1"
    },
    "updatedAt": "2020-02-18T20:50:14.092Z",
    "username": "tomjones"
}

In addition, the _embedded resources returned by the request can be used as a navigation option to explore related resources. For example, population is returned as an _embedded resource in the response, and you can use the embedded resource’s self link to initiate a GET /environments/{{envID}}/populations/{{popID}} request to return data about the population associated with this user.

Relationships, links, and references

Relationships between resources or operations can be described as follows:

Relationships (one-to-one)

Where a resource is directly related to another resource (such as employee to manager, user to population, logo to brand), the relationship is generally represented by an attribute as a first-class citizen of the resource. For example:
- _links object : Contains an href to the actual resource.
- Payload : Contains the reference as an attribute with the ID. The name of the _links attribute and the attribute in the payload must be the same).
- Expandable : Yes.
Relationships (one-to-many or many-to-one)

Where a resource or resources may be related to a collection or to many resources. For example, a user to group membership:
- _links object : Contains an href to the actual resource or collection.
- Payload : May contain the reference as an attribute with the ID. The name of the _links attribute and the attribute in the payload must be the same).
- Expandable : No.
Informal relationships and links

Provides navigation and self-discovery of the API and its related resources (such as next page of search results, next authentication service to invoke, or with which environment the resource is associated). For example:
- _links object : Contains an href to the actual resource, collection, or URL.
- Payload : Cannot contain the reference as an attribute.
- Expandable : No.

These relationships and references are represented as follows:

Links are represented using JSON HAL conventions (such as in a _links object).
Links are represented as absolute URLs.
Links can be expanded using the expand parameter. The links can also be referenced using the "property-as-resource" pattern.
References as attributes have an id value and can also have additional attributes (such as displayName).

For information about error messages, refer to Error codes in the PingOne Platform API Reference.

Caching

The PingOne API generally implements HTTP caching of operation responses. When HTTP caching is implemented, the following HTTP response headers are included:

ETag

An arbitrary string for the version of a representation. This includes the media type in the hash value. For example: ETag: "686897696a7c876b7e".
Date

The date and time the response was returned. For example: Date: Sun, 06 Nov 1994 08:49:37 GMT.
Cache-Control

The maximum number of seconds a response can be cached. If caching is not supported for the response, the value is no-cache. For example: Cache-Control: 360 or Cache-Control: no-cache.
Expires

If Cache-Control is supplied, this header contains the timestamp for when the response expires. If caching is not supported for the response, this header is not present. For example: Expires: Sun, 06 Nov 1994 08:49:37 GMT.
Pragma

When the Cache-Control value is no-cache, this header is also set to no-cache. If caching is not supported for the response, this header is not present. For example: Pragma: no-cache.
Last-Modified

The timestamp for when the resource itself was last modified. For example: Last-Modified: Sun, 06 Nov 1994 08:49:37 GMT.
Varies

This header is included for user-specific headers (such as Authorization) in multi-tenant scenarios.

PingOne Platform APIs