The following changes have been made to the PingOne APIs or the associated SDKs, by year.

• 2025
• 2024
• 2023
• 2022
• 2021
• 2020
• 2019

2025

2024

2023

2022

2021

2020

2019

More information

For more information about PingOne product updates, refer to Release Notes.

If you want to start building your own workflows with PingOne APIs, the Workflow Library provides step-by-step workflows with linked Postman collections to help you start using the PingOne APIs in your Postman environment. Refer also to Using the PingOne APIs.

For information about how PingOne secures APIs, resources, and data, and what you can do to implement security measures for your PingOne deployment and applications, refer to Platform security.

PingOne API domains

This section discusses how PingOne API regional endpoints are entered in the domain name system (DNS). In DNS, and in our endpoints, the domain part of the uniform resource locator (URL) comprises three parts separated by periods, such as api.pingone.com: one of our service-specific subdomains, our PingOne domain name of pingone, and one of our top level domains.

We use Postman variables to manage this variety of domain parts in PingOne API endpoints. The later discussion is correct regarding the domain part that the variables evaluate to. However, to ease maintenance, the Postman environment template you get when you Download the PingOne Postman collections uses variables to isolate the TLD from the rest of the domain part and to isolate the domain part from the rest of the endpoint.

The environment template has a path variable for each subdomain. Each path variable uses another variable, {{tld}}, for the top level domain (TLD). Such as https://api.pingone.com/v1 for {{apiPath}}. The tld variable is first in the environment template that you downloaded.

The table below shows the top level domain value for each region. To change your region, simply change the default {{tld}} value from com to your region's TLD.

The PingOne API includes the following domains:

The {{...Path}} variable in the sample requests stand for the PingOne service endpoint. Refer to Public endpoints in the PingOne for Developers Foundations guide for more information.

The Try a Request feature

Our documentation for the PingOne APIs includes an interactive Try a Request feature. Try a Request 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.

Requests in Authentication and Authorization APIs do not have the Try a Request feature due to a Cross-Origin Resource Sharing (CORS) constraint.

Calling the PingOne APIs from the command line

Each PingOne API request in the documentation includes an example request and response. By default, the example request is displayed using cURL. However, a number of coding languages are available in the associated drop-down list. If you want to run a request from the command line, you can select the coding language and copy the displayed request. You'll need to replace any variables in the request with the appropriate values before running the request.

Using Postman collection-level authorization

Most APIs require authorization to ensure that client requests access data securely. Postman can pass along whatever authorization details necessary for the method demanded by the endpoint. You can manually include authorization data in the header, body, or as parameters to a request. However, the easiest way is to use the Authorization tab in Postman. Select an authorization Type on that tab and Postman offers a dialog to gather the information required by that Type. When you run a request, Postman uses the information from the Authorization tab to automatically add the necessary authorization header, body, or parameters to the request. Postman offers the Authorization tab on requests, folders, and collections.

In PingOne collections, the authorization method is defined at the collection level. Only those requests that require a specific authorization method have authorization defined on the request (roughly 10% of PingOne requests). This allows you to easily change the authorization used for most requests. Refer to Postman Collection-Level Authorization for more information.

This section provides guidance on what PingOne API client developers should do to maintain forward compatibility of their client applications as PingOne APIs evolve. PingOne is a continuously developing platform, and developers must be aware of non-breaking changes to the APIs and how to prepare for these inevitable changes. PingOne will rarely, if ever, introduce a breaking change; however, when that happens, there will be notifications or deprecation messages to inform developers. For non-breaking changes, client developers must ensure that their apps will function as expected after the following API changes occur.

Non-breaking API changes

Client applications should be resilient to additions of new optional properties in request, response, and event payloads. The following list of enhancements occur regularly to the Pingone platform API.

Related resource links

The addition of new related resource links added to responses should not cause application breaks in your client environments.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "organization": {
            "href": "https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda"
        },
        "license": {
            "href": "https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda/licenses/3f06970a-3235-46cb-b46f-cf6dfee2bb84"
        },

Almost all PingOne API responses include a _links section that lists related resources as HAL (Hypertext Application Language) links, and these lists change as the platform adds new resources (and new relationships). For common endpoints, the list of HAL links changes often.

New optional properties

The addition of new (optional) properties added to request, response, and event payloads should not cause application breaks in your client environments.

PingOne API endpoints, even those that have been part of the platform since its inception, can receive additional optional data model properties as the platform matures. Client application developers must configure their client environments to accommodate new optional properties in requests and support new returned properties in endpoint responses.

New content-types or content-language formats

The addition of new content-types or content-language formats of the same resource should not cause application breaks in your client environments.

The platform API includes endpoints that support multiple content types. Client application developers must configure their application environments to accept supported media types for the endpoint. For example, the following request shows a new action on the /{{envID}}/flows/{{flowID}} endpoint that supports a device authorization grant. Your client environment should support the new content type, application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json.

curl --location --request POST '{{authPath}}/{{envID}}/flows/{{flowID}}' \
--header 'Content-Type: application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json' \
--data-raw '{
    "userCode": "{{userCode}}"
}'

In addition, the PingOne API might (over time) return new content types for a given resource. If a client is retrieving a resource without specifying the exact type that it is expecting, then it must be able to tolerate processing any response content type that satisfies the Accept HTTP header.

For example, a client issues this request:

curl --location --request GET '/some/resource' \
--header 'Accept: */*' 

Initially, GET /some/resource is represented by a Content-Type: application/json response, which satisfies the request's Accept: */*. A client could assume that this response is always application/json and only have code to process such responses.

However, at some later date, GET /some/resource supports a new Content-Type: text/html response, which also satisfies the request's Accept: */*. The platform does not guarantee the choice of Content-Type when multiple values satisfy the request. In such cases, the client could start receiving Content-Type: text/html and process this response incorrectly, expecting it to be JSON.

In cases where clients can receive any content type that satisfies their request's Accept: */* header, the client must be configured to handle any content type that is returned. Or, preferably, clients should be configured to be as specific as possible about the content type they are able to accept.

Case-insensitive request and response headers

It's important that you do not treat request or response headers as case-sensitive. PingOne treats all request headers as case-insensitive, and may change the case of response headers at any time.

The HTTP 1.x and 2.x specifications require headers to be treated as case-insensitive.

New HTTP methods

The addition of new supported HTTP methods added to a resource should not cause application breaks in your client environments.

Client application developers must configure their application environments to accommodate new HTTP methods added to a platform service. For example, adding a new PATCH operation to an endpoint should be supported in your client environments.

Third-party libraries

Some third-party libraries deployed in your client environment can cause failures as a result of the non-breaking API changes listed above. In such cases, configuration of the library objects can resolve the issue.

For example, if your application environment uses the Jackson library to serialize or map Java objects to JSON, it is recommended that you update the object mapper setting responsible for deserializing API responses to prevent deserialization errors when new properties are added to the API response. The recommended setting is: new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);. (Jackson's default setting is true.)

As a backup, you can also annotate Jackson library objects with the @JsonIgnoreProperties(ignoreUnknown = true) property to prevent deserialization errors. Conservative developers may choose to employ both strategies.

Protocol for breaking changes

Ping Identity will only support the current release of the platform APIs.

APIs and resources that are made generally available to all customers for Ping Identity's multi-tenant hosted service products are designed to evolve in a non-breaking fashion rather than rely on versioning to change. In the case of a breaking change that requires an API or a resource to be versioned, the following describes the Ping Identity version support lifecycle:

• The current version of the API or resource will be supported;

• Once a new version of the API or resource is released, the previous version will also be supported for one (1) year; and

• Anytime after this one (1) year period, previous versions of the API or resource will be removed.

< HTTP/2 200 
< api-deprecation-date: Sun, 21 Jul 2019 00:00:00 GMT
< api-deprecation-message: Deprecated, use /environments?filter=orgId eq "{id}" instead

Transient API errors occur because of temporary service interruptions such as network issues, rate limits, server congestion, and other similar occurrences. This topic outlines the recommended best practices for implementing retry-handling logic to maintain resiliency in the applications and integrations with PingOne.

These HTTP status codes indicate temporary issues that can resolve over time, making them ideal candidates for automatic retries by a calling client.

Accounting for latency

API clients can experience latency when creating resources across services in the PingOne platform multi-region architecture, where the newly created resource has not propagated through the system to allow for the successful completion of a follow-up request. For example, if you create a resource with one internal service, it is possible that other internal services might not be aware of that new resource in time for your code's next step. An immediate call to the second resource can fail. Given this potential for latency, all applications should be written to retry the request.

The primary areas that experience latency are:

• Applications and Secrets

  Latency occurs when you create an application and then try immediately to retrieve the system-generated secret.

• Applications and Scopes

  Latency occurs when you create an application and then try immediately to retrieve its resource access grants.

• SAML configuration and attributes

  Latency occurs when you create a SAML configuration and then try immediately to retrieve its attribute mappings.

• Environments, role assignments, and applications

  Latency occurs when you create an environment and then try immediately to retrieve its role assignments or add an application to the new environment.

• Populations and role assignments

  Latency occurs when you create a population and then try immediately to retrieve its role assignments.

Eventual Consistency and retryable 404 errors

Latency most often affects read operations immediately after a create request. For 404 Not Found responses where eventual consistency can delay resource visibility across services, it is recommended that you retry only if:

• You recently performed a successful create operation on a parent resource (such as Environment or Application), and

• The 404 response is received during a GET request for a subordinate resource shortly afterward.

For example, after creating an environment with POST /environments, an immediate follow-up GET /environments/{{envID}}/signOnPolicies might return a 404 briefly. Likewise, after creating an application with POST /environments/{{envID}}/applications, an immediate GET /environments/{{envID}}/applications/{{appID}}/secret might return a 404 briefly until the secret gets generated asynchronously.

Eventual consistency and delete operations

Similar to create cases, eventual consistency can affect reading resources after a delete operation. In these cases, subordinate resources might still be readable for a period of time until the system propagates the delete across services.

For example, after deleting an environment with DELETE /environments/{{envID}}, an immediate read operation on applications with GET /environments/{{envID}}/applications might return some results temporarily. In such cases, it is recommended that you do not retry the original delete and do not delete the currently readable resource(s). The system is eventually consistent and will catch up.

For more information about these status codes, refer to MDN Web Docs HTTP response status codes.

Retry-handling logic with exponential backoff and jitter

Do not simply create a loop that rapidly re-submits the same request over and over. You could unintentionally end up with a status 429, trigger rate limiting, or worse have your IP address blocked. Instead, implement an exponential backoff with jitter that gradually increases the time between retry attempts. Start small and increase exponentially until reaching maximum delay. This allows the server or network time to recover, and your application will get the response it needs.

For example, you can increase the number of seconds between retries in powers of two. If you add jitter, which involves adding randomness to those retry delays, this will randomize backoff retry delays to avoid "retry storms" when multiple clients are in use simultaneously.

// Pseudo code
// Example of an exponential backoff calculator
function calculateExponentialBackoff(attempt, baseDelay) {
    jitter = random(0, 100); // Add random jitter
    return baseDelay * (2 ** attempt) + jitter;
}

Honor the Retry-After header

Status codes 429 and 503 often include a Retry-After header that specifies one of two things, depending on the status code. For a 429, it specifies how long the client should wait before retrying the request, designated in number of seconds. For these cases, your retry handler must wait for the amount of time provided by the service.

For a 503 status code, the Retry-After header specifies when the service is expected to be available, designated in a date format. In both cases, the Retry-After header specifies when your app can reasonably make the request again. You need to do some math on the available date to figure out when you can try again. Or, if the retry delay is too long, then return a friendly error message to the client.

//Pseudo code
//Example of using the Retry-After header
if response.status == 429 or response.status == 503:
    retryAfter = response.getHeader("Retry-After");
    if retryAfter exists:
        wait(retryAfter);
    else:
        delay = calculateExponentialBackoff(attempt, baseDelay);
        wait(delay);

Don't make retry handling a catchall

It's good practice to avoid a catchall approach to errors, particularly if you are implementing retry logic in your API calls. The goal is to create resiliency in your application and provide the best user experience. Do not try to handle all status codes in the same way. The status codes outlined above that support retry logic mean different things with respect to how you should handle them.

The following is an example of an anti-pattern that could result in unintended bad consequences.

//Psuedo code
// Example of bad practice 
switch(statusCode) {
    case 408:
    case 429:
    case 500:
    case 502:
    case 504:
    case 503:
        //callout to service 
    default:
        //catchall for other status codes
}

Fail gracefully

If you reach the maximum number of retries without a successful request, it's important to consider how you handle the error. You need to take into account the user experience as well as your business requirements.

Don't return raw error responses to the user. Provide a useful, friendly error message with instructions on how to retry later or who to contact. If there are business implications to not making a successful request, first consider what operations might need to be rolled back, and any logging that should occur, before or simultaneously with your client error message (particularly in authentication and authorization transactions). You might need to revoke tokens or sessions, depending on your use case.

Security considerations

To avoid exposing your applications to vulnerabilities or attacks, it is important to design your retry handler properly. The following factors should be considered.

• Maximum retry counts

  If your retry logic supports an unlimited number of retries, you could expose your application to resource exhaustion attacks. Attackers can use your application as a proxy for denial of service (DoS) attacks against PingOne APIs or as a conduit for brute force credential-stuffing attacks.

  Consult with your app owners and security teams to determine a reasonable number of retries. Set that as the maximum number of retries in your retry handler in a way that cannot be overridden.

• Validate reasonable Retry-After limits

  Similar to the best practice of validating input data at the client and server, you should also validate the Retry-After header in API responses when the status code is 429 or 503. Man-in-the-middle attacks could result in manipulation of the response headers, and an attacker could reset the value to 1, causing your application to retry too often and get rate limited, or worse, have your IP address blocked. Likewise, attackers can reset the value to an extremely long wait time, like 172800 (2 days), causing your customers to abandon your application before a transaction is completed.

  If no Retry-After header is present, make sure you have reasonable values set in your exponential-backoff variable number of seconds to avoid rate-limiting, IP blocking, or retry storms.

• Check for token expiration

  If your application is retrying requests, keep checking the HTTP status code in case it changes to a 401 (unauthorized), or 403 (forbidden). During your retry attempts, your token could expire, and you should switch to re-authentication before trying again. If you're using OAuth/OIDC, and depending on your security requirements, you have options for silent authentication with the prompt="none" parameter, the login_hint_token request parameter, or using refresh tokens to get a new token before retrying. These options provide a better user experience rather than forcing users to login again.

• Alert excessive failures

  Monitor, log, and alert the number of attempts a user or customer submits while using your application to retry these API calls (if you have that capability from your client application). It could be a sign of a misuse or abuse case you need to handle.

Sample retry handler

The following psuedo code sample shows these retry logic best practices.

// Pseudo code
//Example of retry logic
function callApiWithRetry(apiEndpoint, maxRetries = 5, baseDelay = 1000) {
    let attempt = 0;
   
    while (attempt < maxRetries) {
        response = makeApiCall(apiEndpoint);

        // Success Case
        if response.status == 200 || response.status == 202:
            return response.data;

        // Handle Transient Errors
        if response.status in [408, 500, 502, 504]:
            delay = calculateExponentialBackoff(attempt, baseDelay);
            wait(delay);

        // Handle Rate-Limiting
        else if response.status == 429 or response.status == 503:
            retryAfter = response.getHeader("Retry-After");
            if retryAfter exists:
                wait(retryAfter);
            else:
                delay = calculateExponentialBackoff(attempt, baseDelay);
                wait(delay);

        // Handle Authentication Failures
        else if response.status == 401 or response.status == 403:
            refreshToken(); // Secure token refresh or re-authentication
            continue;

        // Handle other errors (No retries)
        else:
            handleError(response); // Sanitize and log the error
            throw Error("Request failed with status code: " + response.status);
       
        // Increment Retry Counter and Monitor
        attempt += 1;
        monitorRetries(apiEndpoint, attempt); // Security monitoring for abnormal retry behavior
    }
   
    // Fail Gracefully After Max Retries
    throw Error("Max retries reached. Request failed.");
}

function calculateExponentialBackoff(attempt, baseDelay) {
    jitter = random(0, 100); // Add random jitter
    return baseDelay * (2 ** attempt) + jitter;
}

We use Postman to create our PingOne API docs, and have supplied our Postman collections for you to download. There's also an accompanying Postman Environment template already populated with the variables used in the collections.

If you aren't currently using Postman, you can install the free version. Refer to Download Postman to install Postman, either locally, or in your browser.

Refer to The PingOne Postman collections for the collections you can download or fork.

For more information about our Postman environment variables, refer to The PingOne Postman environment template.

You'll also find all of the Postman collections for our documented PingOne use cases in our Workflow Library.

You can get here the PingOne Postman collections used for the Getting Started workflows, as well as the collections for all of our Platform APIs. You've two methods for retrieving a Postman collection into your workspace:

1. Fork the collection into your workspace. Postman retains an association between the source and your fork. If we update the source collection, you can pull those changes into the fork in your workspace.

2. Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.

To retrieve a collection

Refer to The PingOne Platform collections on this page.

1. Click the collection's Run In Postman button.

2. At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.

   Note: You need to be logged in to your Postman account to retrieve the collection.

   

3. Follow the on-screen instructions to fork or import the collection. You're prompted to select a Postman workspace for the retrieved collection.

When you fork a Postman collection, you create a copy of it in a selected workspace. Forking a collection creates a linked version that synchronizes with its source collection. This synchronization is apparent when you click the three dots icon on the forked collection - you'll see Pull changes on the context menu. When you click Pull changes, Postman compares the fork to the source collection. If changes are available, you can pull those changes into your fork. If you also elect to watch the collection, you'll receive notifications when the source changes.

If you import a collection, a copy is created in the selected workspace with no link back to the source. The collection is static. This may be desirable for some use cases. For example, if you intend to keep and use only some requests in a collection, a link back to the source is not needed.

You're not limited to choosing one method or the other. You can fork a copy to track the source and import a copy for experimentation, if you like.

The PingOne Platform collections

These Postman collections include requests for all create, read, update, and delete (CRUD) operations for the PingOne Platform APIs.

Collection	Description	Retrieve
Platform	Postman requests for the PingOne Platform API. Includes all environment variables. No example responses to make it easy to get started.
Platform	Postman requests for the PingOne Platform API. Includes all PingOne Platform API Reference documentation and example reponses. No environment variables are included.

For more information about the Postman environment variables included when you download or fork one of our Postman collections, refer to The PingOne Postman environment template.

Our Postman collections use variables in the request URLs to specify the UUIDs for PingOne resources. When you click the Run in Postman button for a collection, these environment variables are included in your download or fork. Use these environment variables as a template to assign your PingOne resource UUIDs with the common variables used in many of the requests.

For more information about using Postman environments, refer to the following topic in the Postman documentation: Environments in Postman.

POST requests in the PingOne Postman collections that create a resource and return a resource ID include a Postman script. This script automatically adds a resource variable to your active Postman environment, and uses the newly created ID as the value.

For example, the following request creates a new user. This request URL contains variables for the API path and environment ID:

POST {{apiPath}}/environments/{{envID}}/users

To run this request, you must ensure the {{apiPath}} in the Postman environment template has the regional top-level domain (TLD) associated with your organization. Refer to Variables you must value for more information.

Almost every request in PingOne requires an environment ID. If you are working primarily in one environment for testing purposes, you'll want to add your environment's UUID to your active Postman environment as the value for the {{envID}} variable.

Requests to PingOne Management API endpoints require a valid access token to authenticate the request. In the PingOne Postman collections, the token value is represented in the Postman environment template as the variable {{accessToken}}.

With the {{tld}} and {{envID}} variables defined in your Postman template, and with a valid token value defined in the {{accessToken}} variable, you can run the request shown above:

POST {{apiPath}}/environments/{{envID}}/users

If the request is successful, Postman adds a {{userID}} variable to the current Postman environment automatically, and associates the new user's id property value (the UUID of the new user) with this variable.

Notes about environment variables and security

It's important to understand how Postman allows you to Store and reuse values using variables. Postman has two values for each environment variable: an Initial value and a Current value. You'll want to pay particular attention to differences between Initial and current values. Initial values are saved to Postman's cloud, and available to anyone who has access to the environment. Current values are saved only locally and available only to you. Postman uses only the current value in requests. If an environment variable has an initial value but no current value, Postman doesn't copy it to the current value or use the initial value in the request, the request simply fails. In this case, you need to manually copy the initial value to the current value.

When you create a new variable with an initial value and save the environment, Postman autofills the current value. However, that is the only time that Postman autofills the current value. If you subsequently delete the current value, the variable is no longer valued in a request.

Saving initial values to the Postman cloud impacts security. These initial values are available to anyone who has access to the workspace. If a workspace is public, you have a security issue.

Postman's recommended solution to exposing secrets is to Store secrets in your Postman Vault. Remember that Postman uses only current values in requests.

Variables you must value

When you download or fork a PingOne Postman collection, your workspace receives a set of Postman environment variables for you to use as a template. The variables that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. Our script associated with the request (shown on the request's Scripts tab) inserts the identifier of the resource it creates as the value of the variable associated with that resource. However, some variables essential to using Postman with PingOne do not have their values inserted automatically. You must manually add the correct value to these variables before making any requests in Postman:

For information about integrating PingOne services with other Ping Identity products, refer to the following integration guides:

• To integrate the PingOne platform with PingFederate, refer to Federating PingOne and PingFederate.

  Note: The client id for the PingFederate integration is always in the form of pf-sso:{environmenID}. You can get the client secret by calling the client ID/secret endpoint if you have the permissions for the environment. The rest of the integration is generated on the front end using the same environment ID.

• To integrate PingOne MFA with PingFederate, refer to Overview of the PingOne MFA Integration Kit.

• To integrate PingOne Risk with PingFederate, refer to Overview of the PingOne Risk Integration Kit.

Integration Catalog API

The PingOne integration catalog API enables developers to discover and retrieve integration metadata and download integration kits as a compressed file. For more information, refer to Integration Catalog. For use cases, refer to the Workflow Library.

Application resources define the connection between PingOne and the actual application (also known as a client connection). The application type you choose to create includes default settings that you're free to change. For example, you can configure the settings for a Single-Page application to match the settings for a Web application. This is by design for maximum flexibility.

Learn more in Applications in the PingOne admin guide.

When you make a request to create a new application, you must specify the type property that specifies one of the following application types:

• Web application

  A browser-based application with a server-side component, such as ASP, CGI, JSP/Java, Node.js, or Ruby on Rails applications.

• Native application

  An application that is installed and run directly on the local operating system, like Java, Objective-C, Swift, or React applications. Native applications are typically intended for mobile devices. These native applications are optionally configured using the mobile property.

• Single-Page application

  A browser-based application that runs on the front-end with no server-side component, such as Sencha Touch, AngularJS, and React applications. A single page application runs on the client side after it loads, so it cannot keep a client secret.

• Non-interactive

  A web application that does not require user interaction through the web browser, like a command line interface, a service, or a daemon.

• Worker

  An administrator application that can interact with platform APIs. Access to platform APIs is determined by the user's or application's role assignments. The role assignment for a Worker app is set by the assignActorRoles property.

• Device authorization

  Creating an application of this type initiates an action that returns an activation code to the end user. This enables you to obtain authorization from the end user through (what is typically) a mobile device.

• Platform applications

  PingOne creates platform applications (PingOne Admin Console, PingOne Application Portal, PingOne Self-Service - MyAccount, and PingFederate-SSO) when the environment is created. The PingFederate-SSO platform application is created only if the PingOne environment includes PingFederate, and unlike the other platform applications, PingFederate-SSO application information is not returned through a GET request.

These are the default grantTypes, response_type, and tokenEndpointAuthMethod attributes for the application types:

Use Cases

• Configure a Non-Interactive Worker Application

• Configure an Interactive Worker Application

• Configure an application with an authorization code grant

• Configure a single-page application with an implicit grant

• Test a SAML application connection

• Test an OIDC Application Connection

• Configure an Application with a Refresh Token Grant

• Configure a Single-Page Application with PKCE and an AuthCode Grant

Managing applications

The base endpoint, /environment/{{envID}}/applications, provides endpoint operations to create, read, update, and delete OIDC and SAML application connections. There are POST request examples to show the required properties to create each type of application connection. For more information, refer to Application Operations.

The secret endpoint, /environments/{{envID}}/applications/{{appID}}/secret, provides endpoint operations to read and update the application's secret, if the requesting actor has a superset of the application's role assignments. For more information, refer to Application Secret.

Applications support the following additional configuration properties:

• Application resource grants

  The application resource grants endpoint, /environments/{{envID}}/applications/{{appID}}/grants, provides endpoint operations to create, read, update, and delete the resource grant associated with the application connection. For more information, refer to Application Resource Grants.

• Application sign-on policy assignments

  The application sign-on policy assignments endpoint, /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments, provides endpoint operations to create, read, update, and delete the sign-on policies associated with the application connection. For more information, refer to Application Sign-On Policy Assignments.

• Application role assignments

  The application role assignments endpoint, /environments/{{envID}}/applications/{{appID}}/roleAssignments, provides endpoint operations to create, read, update, and delete the role assignments associated with the application connection. For more information, refer to Application Role Assignments.

• Application attribute mapping

  The application attribute mapping endpoint, /environments/{{envID}}/applications/{{appID}}/roleAssignments, lets you customize the content of an ID token or a SAML assertion by adding custom attributes and their values. For more information, refer to Application Attribute Mapping.

• Application MFA push credentials

  Push credentials are required for sending push notifications to a native application. The endpoint, /environments/{{envID}}/applications/{{appID}}/pushCredentials, provides endpoint operations to create, read, update, and delete the push credentials associated with the application connection. This section provides examples for both APNS and FCM push credential types. For more information, refer to Application MFA Push Credentials.

Related topics

The Applications service implements operations to create, read, update, and delete, applications resources.

Cross-origin resource sharing

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:

/{envId}/as/authorize
/{envId}/as/resume
/{envId}/as/signoff
/{envId}/rp/authenticate
/{envId}/rp/callback/{callbackId}
/{envId}/saml20/idp/sso
/{envId}/saml20/idp/startsso
/{envId}/saml20/resume
/{envId}/saml20/idp/slo
/{envId}/wsf/sts/{appId}
/{envId}/wsf/mex/{appId}
/{envId}/wsf/prp/{appId}
/{envId}/wsf/prp/resume

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

/{envId}/as/txs 
/{envId}/saml20/sp/sso
/{envId}/saml20/sp/acs
/{envId}/saml20/sp/jwtacs

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:

• Accept
• Accept-Language
• Content-Language
• Content-Type
• Range
• Authorization
• Content-Length
• Cookie
• Correlation-Id
• Origin
• Origin-Cookies
• Referer or Referrer
• X-Amz-Date
• X-Amz-Security-Token
• X-Api-Key
• X-client-version
• X-Content-Type-Options

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.

Applications data models

The following applications properties tables show the base data model for properties that apply to all application protocols, and the specific properties for the OpenID Connect (OIDC), SAML, and WS-Federation application protocols.

Applications base data model

Applications OIDC settings data model

Applications OIDC settings data model for PING_ONE_SELF_SERVICE

For applications of type PING_ONE_SELF_SERVICE only. Ignored for all other application types.

Applications OIDC settings data model for PING_ONE_PORTAL

For applications of type PING_ONE_PORTAL only. Ignored for all other application types.

Applications SAML settings data model

Applications SAML metadata settings data model

Applications WS-Federation settings data model

Applications WS-Federation settings data model (continued)

Additional settings for Microsoft Entra ID hybrid join

Hybrid join simplifies device management and allows organizations to join devices to on-premises Active Directory and the cloud with Entra ID.

Application events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Related topics

ID token and SAML assertion customization

The application attributes service lets you customize the content of an ID token or a SAML assertion by adding custom attributes and their values. Custom attributes have a cumulative length constraint of 16 Kb. Refer to Custom attributes in Schemas for more information.

In the Authorization request header field of all samples, the accessToken value is your full base64url-encoded JSON web token generated by the authentication service.

OpenID Connect application attribute mappings

For OpenID Connect (OIDC) applications, the user claim defined by the custom attribute mapping is returned in the ID token, regardless of the scopes specified in the authorization request. For example, suppose you want to include a user's accountId in ID tokens associated with the specified OIDC application, a custom application attribute resource can be created to map the user's account ID to the accountId PingOne user attribute. The request looks like this:

curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer {{accessToken}}' \
-d '{
	"name": "userAccountID",
	"value": "${user.accountId}",
	"required": true
}'

SAML application attribute mappings

For SAML applications, the user claim defined by the custom attribute mapping is returned in the SAML assertion.

For example, suppose you want to include an externalId in assertions associated with the specified SAML application, a custom application attribute resource can be created to map the SAML externalId attribute to the user's external ID attribute. The request looks like this:

curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer {{accessToken}}' \
-d '{
	"name": "externalId",
	"value": "${user.externalId}",
	"required": true
}'

Advanced attribute mapping

You can use PingOne's expression language for advanced attribute mapping. The supported expression language is an augmentation of SpEL. SpEL is a powerful expression language used for querying and manipulating an object graph at runtime.

For example, with advanced attribute mapping capabilities, you can write an expression that concatenates two or more user attributes in the value property:

curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer {{accessToken}}' \
-d '{
	"name": "fullName",
	"value": "${user.name.given + ', ' + user.name.family}",
	"required": true
}'

In this request, the fullName mapped attribute includes the user's first name and last name in the response.

Applications attribute mapping data model