PingOne MFA

Enable Users MFA


Read User MFA Enabled


Update User MFA Enabled

MFA Bypass for User


Allow MFA Bypass for User


Check MFA Bypass Status for User

MFA Devices


Create MFA User Device (Voice)


Create MFA User Device (Email)


Create MFA User Device (TOTP)


Create MFA User Device (FIDO2)


Create MFA User Device (SMS)


Create MFA User Device (OATH token)


Create MFA User Device (WhatsApp)


Create MFA User Device for testing


Resend Pairing Code


Set Device Order


Remove Device Order


Activate MFA User Device (OATH token)


Activate MFA User Device


Activate MFA User Device (FIDO2)


Unlock MFA User Device


Block MFA User Device


Unblock MFA User Device


Read All MFA User Devices


Read One MFA User Device


Update Device Nickname


Send MFA Device Logs


Delete MFA User Device

MFA Pairing Keys


Create MFA Pairing Key


Read One MFA Pairing Key


Delete MFA Pairing Key

MFA Device Authentications


Initialize Device Authentication


Device Authentication (Custom Notification)


Device Authentication (No User Name)


Device Authentication (One-time SMS)


Device Authentication (One-time Voice)


Device Authentication (One-time Email)


Select Device for Authentication


Validate OTP for Device


Check Assertion (FIDO Device)


Cancel Device Authentication


Read Device Authentication

MFA Authentication Code


Create Authentication Code


Read Authentication Code


Delete Authentication Code

Device Authentication Policies


Create Device Authentication Policy


Read Device Authentication Policies


Read One Device Authentication Policy


Update Device Authentication Policy


Update Device Authentication Policy (env with PingID integration)


Delete Device Authentication Policy


Migrate Device Authentication Policies

Reporting


Create report of SMS devices - entries in response


Get report results - entries in response


Create report of MFA-enabled devices - results in file


Get report results - results in file - polling

MFA Settings


Read MFA Settings


Update MFA Settings


Reset MFA Settings

OATH Tokens


Create OATH token (TOTP)


Create OATH token (HOTP)


Create multiple OATH tokens


Check status of OATH token creation job


Retrieve all OATH tokens


Retrieve OATH token by ID


Retrieve OATH token by serial number


Revoke OATH token


Revoke multiple OATH tokens


Check status of OATH token revoke job


Resync OATH token


Resync OATH token paired with user

FIDO Policies


Create FIDO Policy - all FIDO-certified authenticators


Create FIDO Policy - FIDO-certified and enterprise


Create FIDO Policy - specific authenticators


Add Custom FIDO Device - u2f


Add Custom FIDO Device - fido2


Read All FIDO Policies


Read All FIDO Device Metadata


Read Single FIDO Policy


Read FIDO Device Metadata - single u2f device


Read FIDO Device Metadata - single fido2 device


Update FIDO Policy


Delete Single FIDO Policy


Remove Custom FIDO Device

Remembered Devices


Create Device Authentication Policy (with Remember Me enabled)


Create Remember Me Device


Check Remember Me Device

Working with PingOne APIs

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. 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 a collection 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.{{tld}}/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.

Region Code Top level domain
North America region (excluding Canada) NA com (default)
Canada region CA ca
European Union region EU eu
Australia region AU com.au
Singapore region SG sg
Asia-Pacific region AP asia

The PingOne API includes the following domains:

Domain Postman path variable Description
api.pingone.{{tld}} {{apiPath}} The primary domain for calling PingOne Management API resource server.
auth.pingone.{{tld}} {{authPath}} The authorization and authentication server domain called to request the access token required to authenticate PingOne API requests.
orchestrate-api.pingone.{{tld}} {{orchestratePath}} The primary domain for calling the PingOne DaVinci Management API resource server.
scim-api.pingone.{{tld}} {{scimPath}} PingOne API service for Cross-domain Identity Management (SCIM).

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.

Postman and the PingOne APIs

We use Postman to create our PingOne DaVinci Admin 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 DaVinci Admin API 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.

The PingOne Postman collections

You can get the PingOne MFA Postman collection by following either of these 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 MFA 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.

    RunInPostman

  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 MFA collection

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

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

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.

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 MFA API 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 MFA variable. This request URL contains variables for the API path and environment ID:

POST {{apiPath}}/environments/{{envID}}/variables

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}}/variables

If the request is successful, Postman adds a {{variableID}} 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:

Postman variable PingOne resource
adminAppID The Client ID of the Worker app you created Create an admin Worker app connection.
adminAppSecret The Client Secret of the Worker app created.
adminEnvID The ID for the environment in which your Worker app resides.
envID The ID for the environment in which you are running your Postman API requests.
orgID The ID for your organization. In the PingOne admin console, select Environment and click Properties to view your organization ID.
tld The top-level domain to use for your environment. This is used in URLs containing apiPath, authPath, orchestratePath, and scimPath.
apiPath The regional domain for the PingOne management server (https://api.pingone.{{tld}}/v1).
authPath The regional domain for the PingOne authorization and authentication server (https://auth.pingone.{{tld}}).
orchestratePath The regional domain for the PingOne DaVinci management server (https://orchestrate-api.pingone.{{tld}}/v1).
scimPath The regional domain for the PingOne SCIM management server (https://scim-api.pingone.{{tld}}).