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:
-
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.
-
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.
-
Click the collection's Run In Postman button.
-
At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.
-
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.
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}} ). |