API requests

A PUT request is a replace operation. Requests submitted using PUT will replace attribute values specified in the request and clear any attribute values that aren’t specified.

A null value is represented in a resource by omitting the property, although you can specify null to explicitly clear the value.

A PATCH operation performs partial updates of a resource. The body of a PATCH operation is similar to that of a PUT operation. However, omitting an attribute in a PATCH operation results in the attribute being ignored.

You can use a value of null to explicitly clear the value.

The PingOne API supports JSON as the data exchange format with UTF-8 character encoding required for request body content. For PUT, POST, and PATCH operations, the Content-type request header identifies the format of the request body. A Content-type request header value of application/json specifies the data exchange format as JSON, which, by default, sets the character encoding to UTF-8. Here is a sample:

For clarity of request variations, we present the example requests in our documentation as though they’re separate endpoints.

For example, the POST Create Application operation has several request variations. Rather than showing multiple examples, we break this down into multiple reference pages.

PingOne data models list the possible properties in a request or response body for each endpoint at a high level. The data models have five columns, described below.

Resources in PingOne are identified by their associated UUID (universally unique identifier). API requests use UUIDs in the request URL to specify the resources involved in the operation. For clarity, the code samples in this API Reference use descriptive variables such as {{envID}}, {{userID}}, {{appID}}, and {{deviceID}} to represent the UUIDs assigned to PingOne resources.

For example, the following sample request URL specifies a unique device associated with a unique user in a unique environment. The resource ID variables represent specific UUIDs for PingOne resources.

The actual request URL with UUIDs looks like this:

There are a few exceptions to this convention. Notifications template names in PingOne are identified by the template name {{templateName}} rather than by a UUID. For example, the following request URL returns information about a specific template:

The {{templateName}} variable is replaced by one of the pre-defined notifications template names in PingOne. The actual request URL that uses a defined notifications template called strong_authentication looks like this:

Some requests use placeholder syntax to reference platform resource entities as variables. When placeholder syntax is required, the PingOne resource used as a variable is expressed in placeholder syntax format as ${attribute}. For example, when mapping a SAML name attribute to the PingOne username attribute, the value of the PingOne attribute in the POST request body is expressed as ${user.username}. In most cases where placeholder syntax is required, the placeholder references attributes in the PingOne user schema. The variable is written as a path to the value: ${user.path.to.value}. For example, to reference the name.family user attribute, the variable is written as ${user.name.family}.

Placeholder syntax is also used to express sign-on policy condition variables. For example, a condition variable to specify the last completed time the password authenticator was used for sign on is expressed as ${session.lastSignOn.withAuthenticator.pwd.at}.

Placeholders in sign-on policy conditions often specify a value or range of values to meet the sign-on condition. For example, the sign-on policy associated with the following condition prevents sign-on from devices that contain the remote IP address value specified by the variable ${flow.request.http.remoteIp} in the specified IP address ranges.

Placeholders are also used to specify external identity provider attributes. For example, to specify a Facebook attribute that is mapped to a PingOne attribute, the Facebook attribute is expressed as ${providerAttributes.<Facebook attribute name>}. For example, the following expression maps the PingOne username attribute to the Facebook email attribute.

The following table shows the PingOne resources that use Placeholder syntax in POST requests.

Request model and query parameters expandable sections are included in our API documentation when applicable.

For an example of each, refer to the expandable Request model and Query parameters sections in Create Application (OIDC Protocol - Worker App).

You can optimize the information returned by a request through link expansion. Link expansion is helpful when you need the query to return detailed information from an additional resource in the response data. You can identify a resource to expand using the expand query string parameter in the request.

Here is a sample that requests data for a specific user and expands the passwordPolicy attribute to show the password policy’s attribute data.

When using the expand parameter in the request, the returned JSON includes an embedded passwordPolicy resource to show the details of the password policy associated with this user:

Our documentation includes an interactive Try a Request feature. The Try a Request feature enables you to configure and send a PingOne API request and get a response from within the documentation. This is a quick way to interactively test a PingOne API request without needing to use either Postman or the command line.

The Try a Request option is shown at the end of each API reference page. For an example, try the Try a Request button in Create User.

PingOne API documentation includes example requests for each operation. By default, the request is shown in cURL, however, the programming language can be changed by selecting the Language drop-down.

The image below shows the Language drop-down in the example request in Create User.

PingOne supports cross-origin resource sharing (CORS), which gives applications running at different domains permission to access resources on PingOne servers. For example, an application at https://myapp.com that uses PingOne to authenticate users needs to request permission to access resources at https://auth.pingone.com before authentication operations are executed. In this case, a request is made to the resource owner (auth.pingone.com) from the requestor (myapp.com) using CORS headers to ask for access privileges. The response from auth.pingone.com returns the CORS Access-Control-Allow-Origin header with a value that confirms the requestor’s access rights.

PingOne servers are configured to trust all origins when using access tokens. However, when requesting sensitive resources that use PingOne session cookies for authentication, only specified origins will be trusted. The following endpoints require session cookies for authentication, and only the origins specified in the application’s corsSettings property will be trusted when calling these endpoints:

When using session cookies for authentication, no origins will be trusted when calling these endpoints:

Consequently, when defining an application’s connection to PingOne, you generally do not need to add your application’s domain to a list of trusted origins. Cross-origin requests that use HTTP methods to modify the resource, such as PUT, PATCH, POST, and DELETE, trigger a preflight request to ensure that the initial request can be sent. The browser initiates a preflight HTTP OPTIONS request to verify that the HTTP method used in the actual request is allowed. In these cases, the response from auth.pingone.com to the preflight request returns a response with the CORS Access-Control-Allow-Methods header to specify the allowed methods.

When making CORS requests, only these headers can be used:

When accessing CORS responses, you’re restricted to reading only the Correlation-Id header (as well as the request body).

Attempting to submit or access headers that are not listed above may prevent you from making CORS requests or reading the responses.

PingOne truncates a float value submitted in the JSON request body to a matching int value for services other than flow orchestration. For example, in the following request body JSON, the minAgeDays value can be submitted with a value of 1.5.

The request will execute. However, the response shows that the minAgeDays value is converted automatically to an int value:

Note that the value of the floating point number is not rounded. It is trimmed by removing the decimal portion of the value.

For flow orchestration services such as sign-on policy actions, float values submitted in the JSON request body generate an INVALID_VALUE error. For example, the following request body with a priority attribute value of 1.5 generates an error:

The response error looks like this: