Terms that you'll use in this section:

• Environment

  Although an environment is automatically created for you when you first sign on to PingOne, for the purposes of testing PingOne workflows, you'll create an additional, new environment.

• Worker app

  A Worker app is an admin-level application connection that interacts with the PingOne APIs on your behalf. The access token associated with a Worker app gives you admin-level access to all of the PingOne APIs. A Worker app's authorized access to the PingOne API resources is determined by the roles and associated permissions that you assign to the Worker app. By default, these roles and permissions are inherited from your user when you create the Worker app.

• Access Token

  An access token is required to authenticate any calls to the PingOne Platform APIs. The access token is valid for one hour.

• Population

  A population is a collection of users within an environment, similar to an organizational unit (OU). This gives you a way to manage and apply operations to a large set of users.

The diagram below shows how these entities interact.

You'll use our Postman collections to complete the stepped instructions for using the PingOne APIs. This makes it easy to see and use the API calls. There is a separate Postman collection for each set of stepped API instructions, with a link to import or fork the associated Postman collection.

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

Each of our Postman collections contains environment variables that are used by the associated set of APIs. We've already set the values for these environment variables. Additionally, we've included in the collections Postman test scripts that set the necessary environment variable or variables as you move through a workflow. All that's left for you to do is to see, and hopefully understand, what's needed to use the PingOne APIs, and how PingOne workflows operate.

For more information about our Postman environments, see The PingOne Postman environment template.

The Postman public collections include requests for all create, read, update, and delete (CRUD) operations for the PingOne Platform APIs, the PingOne MFA APIs, the PingoOne Neo APIs, and the PingOne Protect APIs. The downloads also include a PingOne Postman environment template to help you assign values to variables in the request URLs.

For more information about the Postman environment template, see The PingOne Postman Environment Template.

You have 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 Ping Identity changes 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 the collection:

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 might be prompted to open your Postman app and to select a Postman workspace for the retrieved collection.

When you fork a Postman collection, you create a copy of it in a different 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 will see Pull changes on the context menu. Click Pull changes and Postman compares the fork to the source collection. If changes are available, you can pull those changes into your fork. If you also watch the collection, you receive notifications when the source changes.

If you import a collection, a copy is created 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 consume only portions of the collection, a link back to the source is not needed.

One need not choose one or the other - you can fork a copy to track the source and import a copy for experimentation!

The environment downloaded with the collection of requests contains every variable used in the collection. Each request that creates a new object with an id has a script that:

1. If not available, creates an environment variable unique to that service.

2. Assigns the id of the newly created object to that environment variable.

The Postman collection uses variables in the request URLs to specify UUIDs for PingOne resources within your organization. When you click the Run in Postman button, the environment variable template downloads and installs automatically. With this environment template, you can associate your PingOne resource UUIDs with the common variables used in many of the requests.

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

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

For example, the following request from the PingOne Postman collection 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 associated with your organization. See 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 should add your environment's UUID to the active Postman template as the value for the {{envID}} variable. In addition, requests to PingOne Management API endpoints require a valid access token to authenticate the request. In the PingOne download 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. If the request is successful, Postman adds a {{userID}} variable to the Postman template automatically, and it associates the new user's id property value (the UUID of the new user) with this variable.

Notes about environment variables and security

It is 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. 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 does not copy it to the current value or use the initial value in the request, the request simply fails. You must manually copy the initial value to the current value.

In Sharing and persisting data, Postman states: "When you create a new variable in Postman, if you leave the current value empty, it will autofill with the initial value." Note that opening clause: "When you create a new variable in Postman"! 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 cloud impacts security, especially if a workspace is public, because initial values are available to anyone who has access to the workspace. If a workspace is public, then literally the entire world can view!

While documented, Postman now emphasizes security of initial values as discussed in Announcing security updates to the Public API Network: new secret-protection policy. The recommended solution to exposing secrets is to Store secrets in your Postman Vault. Use the Postman Vault to Create and manage vault secrets. Remember that Postman uses only current values in requests!

To use a vault variable as the value for another Postman variable, you must add your vault variable to the initial value for your teammates to view and to the current value for a request to use it. For example, a request uses an environment variable called my-secret. One user may choose to use the current value to store their value and leave the initial value blank. Another user may choose to use a Postman Vault variable, such as my-secret-vault, as the value. The former user must ensure that they do not use the initial value if they do not wish to share its value with the team. The latter user can safely use {{vault:my-secret-vault}} as both the initial value and the current value because Postman saves only the text: the name of the vault variable as the text literal, {{vault:my-secret-vault}}. At run time, Postman acquires the value from the user's Vault.

As seen in the previous example, the vault variable need not be named the same as the environment variable. A Postman Vault is exclusively yours and its variables are available for use anywhere Postman variables are used. Thus, if you have multiple environments and each has a different value, then you must differentiate the variable names in your Vault. If you had a PROD environment and a STAGE environment, then you could have my-secret-prod and my-secret-stage in your vault for the two environments.

Variables you must value

When you download the PingOne Postman collections, your workspace receives a Postman environment variable template. Variables in the environment variable template that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. A script on the Tests tab of each create request 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 are not valued automatically. You must manually add the correct value to the variables in this table before you make any requests in Postman.

Set tld to the top level domain of the region appropriate for your environment:

To make calls to the PingOne Platform API, you must get an admin-level access token from a Worker app and submit this access token whenever you make an API request.

Use the PingOne admin console to create a Worker app connection in your initial PingOne environment created when you first signed on:

1. Log in to the PingOne admin console. For more information about the PingOne admin console, see Accessing the admin console home page.

2. Select Applications --> Applications.

   

3. Click the + icon next to Applications to add a new app.

4. In the Application Name field, enter an application name, and select Worker as the Application Type.

   

5. Click Save.

6. Click the toggle at the upper right to enable the application.

7. The environment ID, Worker app Client ID, and Worker app Client Secret is displayed.

   

   Note: You're also able to get the access token assigned to the Worker app here, but for the purposes of this tutorial, we'll show you how to get the access token using a PingOne API request.

8. Select the Roles tab, and click Grant Roles. The best practice is to reduce the roles assigned to the Worker app to only those necessary. For this tutorial, grant the roles and permissions as shown.

   

9. Click Save.

10. The roles and permissions you've granted are then displayed. They should look like this:

    

You'll need the Client ID and Client Secret associated with your Worker app when obtaining an admin access token in the next workflow to Create your test environment.

Although an environment is automatically created for you when you first sign on to PingOne, for the purposes of testing PingOne workflows, you'll create an additional, new environment.

Prerequisites

• The Organization Admin role is required to create an environment. You're assigned the Organization Admin role when you create a PingOne account.

• A Postman installation. If you aren't currently using Postman, you can install the free version. See Download Postman to install Postman.

• Import or fork the Postman collection into your Postman installation. Click the Run in Postman button below. You'll use this collection for the test environment workflow:

  

  For more information about using Postman environments, see The PingOne Postman environment template.

• When you open the Postman collection, ensure that you select PingOne Postman Environment Template for use with the collection:

  

Now that you have a test environment set up, complete the following PingOne sign-on workflow to test your new environment. You will create an OIDC Web app, get the new web app's secret, and initiate an authorization request.

This workflow uses the environment, access token, and test user that you created in Create your test environment. Rather than using the PingOne admin console to create an OIDC Web app, you'll create the web app using the API request.

Prerequisites

• A Postman installation. If you aren't currently using Postman, you can install the free version. See Download Postman to install Postman.

• Import or fork the Postman collection into your Postman installation. Click the Run in Postman button below. You'll use this collection for the test environment workflow:

  

  For more information about using Postman environments, see The PingOne Postman environment template.

• When you open the Postman collection, ensure that you select PingOne Postman Environment Template for use with the collection: