The multi-factor authentication settings (MFA) control whether a user can authenticate using MFA actions. This endpoint enables or disables MFA capability.

For information about user MFA device management, refer to MFA devices.

MFA settings data model

Response codes

You can use the bypassMFA endpoint to define a period during which a specific user should be allowed to bypass MFA. You can also use the endpoint to check whether a specific user is currently permitted to bypass MFA.

To enable multi-factor authentication (MFA), the user resource must have an MFA method associated with its user ID. PingOne supports email, SMS, voice, TOTP authenticator application, and native application method types for use in an MFA flow. Multiple MFA methods can be associated with a user ID. MFA methods must be in the active state to be used in the multi-factor login flow.

With this API, MFA methods are called MFA devices. The devices endpoints provide operations to manage device resources associated with a specified user ID. You need the Identity Data Admin role to perform operations on device resources.

Device order

With the release of the device order feature (Jan 11, 2021), the active devices of most users now have an order (first...last). By default, the order is according to the device activation time (oldest...newest). Each subsequently activated device is appended to the end of the order list. The first device on the list is designated the default device. In most cases, the default device is automatically used for authentication; users no longer need to select a device.

There are a small number of users whose devices do not have a default order with this feature. If a user has more than one active device as of the release of the device order feature, the current active devices and subsequently activated devices have no order. The user therefore has no default device and must choose a device each time they authenticate. In this case, the order must be explicitly set (refer to Setting device order).

Cases where the default device is not used for authentication

In most cases, the default device is automatically used for authentication. However, there are two exceptions:

• If authenticating from a native app and device authorization is enabled, the native device is used for seamless authentication (refer to Automatic device authorization under PingOne MFA Native SDK Flows).
• If the user is paired with a FIDO2 platform device and a session token cookie exists on the browser, the FIDO2 platform device is used for authentication even if it is not the default device.

Setting device order

The operation POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices with required header Content-type: application/vnd.pingidentity.devices.reorder+json explicitly orders a user's existing active devices according to the request body. The active device listed first becomes the default device.

After this operation explicitly sets device order, subsequently activated devices are appended to the end of the order list. You can use this operation to explicitly reorder active devices as many times as needed.

Retrieving an ordered list of devices

The operation GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices returns the list of active devices sorted in their order, with the default device listed first. Devices with a status of ACTIVATION_REQUIRED are listed after the active devices, in no particular order. If devices have no order, GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices returns the list of devices in no particular order.

You can expand the GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results with the expand=order query parameter. The response is then expanded to contain an array of activated device IDs listed according to device order. If devices have no order, an empty array is returned.

Deleting a default device

If the default (first) device is deleted, the second active device on the order list becomes the default device.

Removing device order

The operation POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices with required header Content-type: application/vnd.pingidentity.devices.order.remove+json removes the ordering on a user's active devices. With the execution of this operation, the user no longer has a default device.

Custom device pairing notification with device creation

To send a custom device pairing notification when a new email, SMS or voice device is created, add the notification property to the request body of POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices. The status of the created device must be ACTIVATION_REQUIRED.

{
    "notification": {
        "template": {
            "locale": "en",
            "variant": "variant_B"
            "variables": {
                        "sum": "1,000,000",
                        "currency": "USD",
                        "recipient": "Charlie Parker"
            }
       }
    }
}

When the device is created, a request is executed to select the content for the notification. The notification template is device_pairing. The deliveryMethod is Email, SMS or Voice, depending on the device created. The locale, variant, and all dynamic variables are defined in notification.

For more information on content selection, refer to Runtime logic for content selection. For more information on dynamic varables, refer to Dynamic variables.

Device failure in flows

When the flow returns a NO_USABLE_DEVICES error, and the user has devices that are temporarily unavailable (for example, the device is locked because of too many invalid OTP retries), the IDs of these devices are returned as part of the response.

In the flow response, the status property returns FAILED, and the error message includes the NO_USABLE_DEVICES error code. The following samples show common error messages for a device failure with identified unavailableDevices:

"status": "FAILED",
    "error": {
        "code": "NO_USABLE_DEVICES",
        "message": "Couldn't find authenticating device for user: {{userID}}",
      "unavailableDevices": [
            {
                "id": "edccc773-6f31-4d28-a8e1-0f427d9a9df8"
            }
        ]
    },

"status": "FAILED",
    "error": {
        "code": "NO_USABLE_DEVICES",
        "message": "Daily limit of SMS authentication attempts has been exceeded",
        "unavailableDevices": [
            {
                "id": "7ea99e29-6f8f-42be-af75-232588235e30"
            }
        ]
    },

Device properties

EMAIL device properties

Devices whose type is EMAIL also have the following properties:

SMS/Voice device properties

Devices whose type is SMS or VOICE also have the following properties:

Native device properties

Devices whose type is MOBILE also have the following properties:

Time-based One-time Password (TOTP) authenticator application device properties

Devices whose type is TOTP also have the following properties:

FIDO2 devices

Devices whose type is FIDO2 also have the following properties:

OATH token devices

OATH tokens can be used only in PingOne environments where a PingID account has been integrated.

Devices whose type is OATH_TOKEN also have the following properties:

PLATFORM and SECURITY_KEY webauthn device data model (deprecated, replaced by FIDO2 devices)

Devices whose type is PLATFORM or SECURITY_KEY also have the following properties:

Device order properties

MFA devices events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Filtering result data

You can filter GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results by applying a SCIM filtering expression to the request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set.

SCIM operators can be applied to the following attributes:

The logical operators and and or can also be used to combine filter statements.

For example, the following URL-encoded SCIM filter returns a list of SMS devices that require activation:

{{apiPath}}/environments/{{envID}}/users/{{userID}}/devices?filter=(status%20eq%20%22ACTIVATION_REQUIRED%22)%20and%20(type%20eq%20%22SMS%22)

This URL returns the device that matches the information contained in the specified payload from the PingOne Mobile SDK:

{{apiPath}}/environments/{{envID}}/users/{{userID}}/devices?filter=mobilePayload eq "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz..."

Expanding result data

You can expand GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results with the expand=<value> query parameter. The following value is supported.

Related topics

To enable multi-factor authentication (MFA) via push notification on a native device, the user resource must have a native device and an application associated with its user ID. The association is implemented with a pairing key.

The pairing key endpoints provide operations to create, read, and remove pairing key resources associated with a specified user ID, native device and application. The examples below show common actions to manage pairing keys.

Creating a native device with a pairing key

A user cannot create a native (mobile) device with POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices. The user must create the device with a pairing key:

1. The user installs a native app with an embedded PingOne MFA Native SDK component.

2. The user starts an MFA authentication flow and creates a pairing key. Refer to Multi-factor MFA Action in the Developer Guide for more information.

3. The user scans the pairing key QR code with the native app.

4. The embedded PingOne MFA Native SDK starts the pairing process where the device resource is created. Refer to PingOne MFA SDK for Android or PingOne SDK for iOS.

Pairing key data model

Response codes

The /deviceAuthentications endpoint initiates and completes an MFA action without requiring a call to the PingOne authorize service. It supports actions to select a supported MFA device device type and to validate a one-time passcode (OTP).

When a device authentication MFA flow is initiated, the flow returns a status property in the response that identifies the next action in the flow. The following flow states prompt for a specific flow action:

• OTP_REQUIRED

  For a status value of OTP_REQUIRED, the otp.check action validates the one-time passcode.

• DEVICE_SELECTION_REQUIRED

  For a status value of DEVICE_SELECTION_REQUIRED, the device.select action prompts the user to select a supported device type for use in a multi-factor authentication flow.

• ASSERTION_REQUIRED

  For a status value of ASSERTION_REQUIRED, the assertion.check action validates the assertion.

• PUSH_CONFIRMATION_REQUIRED

  For a status value of PUSH_CONFIRMATION_REQUIRED, a push was sent to the specified mobile device to confirm the authentication.

• PUSH_CONFIRMATION_TIMED_OUT

  For a status value of PUSH_CONFIRMATION_TIMED_OUT, a push was sent to the specified mobile device, but the mobile device did not answer the push during the allowed timeframe.

Device authentications data model

Device authentication events generated

Refer to Audit Reporting Events for the events generated.

The /authenticationCodes endpoint provides operations to create, read, and delete an authentication code. The authentication code (which can be a QR code) enables users to sign on without any data entry, such as providing a username, password, or entering a one-time passcode. The user scans the code, and if successful, gains access to an application's services.

Authentication codes request data model

Authentication codes response data model

For descriptions of other fields under _embedded.device, refer to MFA Devices.

For descriptions of fields under _embedded.user, refer to Users data model.

Device authentication policies (identified in the PingOne UI as "MFA Policies") enable you to configure different settings per MFA authentication method, according to your security policies.

Device authentication policy data model

"fido2" : {
    "enabled" : true,
    "pairingDisabled" : false
}

"mobile": {
    "enabled": true,
    "otp": {
        "failure": {
            "count": 3,
            "coolDown": {
                "duration": 2,
                "timeUnit": "MINUTES"
            }
        }
    },
    "applications": [
        {
            "id": "{{appID}}",
            "push": {
                "enabled": true,
                "numberMatching": {
                    "enabled": true
                }
            },
            "otp": {
                "enabled": true
            },
            "pushTimeout": {
                "duration" : 120,
                "timeUnit" : "SECONDS"
            },
            "pushLimit": {
                "count": 4,
                "timePeriod": {
                    "duration": 10,
                    "timeUnit": "MINUTES"
                },
                "lockDuration": {
                    "duration": 30,
                    "timeUnit": "MINUTES"
                }
            },
            "deviceAuthorization": {
                "enabled": true,
                "extraVerification": "permissive"
            },
            "autoEnrollment": {
                "enabled": true
            },
            "pairingKeyLifetime": {
                "duration": 40,
                "timeUnit": "HOURS"
            },
            "integrityDetection": "permissive"
        }
    ]
}

This table includes the properties that are used for the PingID mobile app. All of the fields in the table below should be enclosed in the mobile object, as in the example in Mobile device authentication policy data model.

Refer to Audit Reporting Events for the events generated.

Related topics

You can use the reporting capability to generate reports containing user and MFA device details, using a number of device-related filters.

For example, you can generate a report listing all email devices or a report containing all of the devices whose phone number starts with a certain country code.

You can use synchronous requests to get back the matching data as entries in the JSON response or use asynchronous requests to have the data provided in a CSV or JSON file. Note that when using the synchronous approach, you may have to make multiple requests if there is a large amount of data.

The request for generating reports uses the dataExplorations endpoint:

https://{{apiPath}}/v1/environments/{{envId}}/dataExplorations

MFA reports data model

Getting the report results

You can receive the report data as entries in the JSON response or as a file (CSV or JSON).

There are a number of ways you can get the report results. The recommended approaches for the most common scenarios are as follows:

• For cases where you anticipate a fairly small number of records in the results:

  • Run a POST request using the expand query parameter. This will create the dataExplorations object and also return the results as entries in the response. {{apiPath}}/environments/{{envID}}/dataExplorations?expand=entries

    For more information on the use of the expand query parameter, refer to "Link expansion" under Conventions.

• For cases where you expect a large number of records, but would like to receive them as entries in the body of the response:

  1. Run a POST request to create the dataExplorations object.

  2. Run a GET request with /entries in the URL: {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}}/entries

  3. If there are too many results to include in one response, the _links section in the response will include a next object. Follow the next link, then using the same access token, run another GET request using the the next link as the URL.

  4. Continue until the response no longer includes a next object.

     For more information on pagination, refer to Paging, ordering, and filtering collections.

• For cases where you want to receive the results as a file:

  1. Run the request to create a report and get the results as a file: POST {{apiPath}}/environments/{{envID}}/dataExplorations. In the body of the request, make sure that deliverAs is set to ASYNC_FILE.
  2. The response to the report creation request will include a status field whose value is IN_PROGRESS.
  3. Run the polling request GET {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}}, using the ID that was returned when you created the report, until the status field in the response equals SUCCESS.
  4. When the response contains the status SUCCESS, it will also include a link for downloading a zipped csv file, a link for downloading a zipped JSON file, and a password for opening the zip files. Use this information to download and unzip the report.
  5. The report itself is cached for two hours, but the links are good for only five minutes.
  6. If more than five minutes has elapsed from the time of the request that returned the links, get updated links by again running the request GET {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}} using the ID that was returned when you created the report.
  7. If more than two hours has elapsed since the report was created, run the report creation request again.

The MFA settings endpoint supports operations to read, update, and reset the PingOne MFA settings associated with a specified environment. A PUT request lets you manage the maximum number of allowed devices for pairing, and it lets you set the device selection option. A successful DELETE operation resets the MFA settings to the default.

Maximum allowed devices

The MFA settings property pairing.maxAllowedDevices defines the maximum number of paired MFA devices each user within an environment can have. This can be any number up to 15. The default value is 5. You can update the setting with GET {{apiPath}}/environments/{{envID}}/mfaSettings and reset the setting to its default with PUT {{apiPath}}/environments/{{envID}}/mfaSettings.

If the maxAllowedDevices value is decreased below the number of paired devices a user currently has, the user's existing paired devices remain. After a paired device is deleted though, the user cannot replace it with a new one. This remains true until the number of existing paired devices is below the current value for maxAllowedDevices.

If the maxAllowedDevices limit is reached and the user attempts to create a new device, an error similar to the following is returned.

400 BAD REQUEST
{
  "id": "<errorId>",
  "code": "REQUEST_FAILED",
  "message": "The request could not be completed. There was an issue processing the request.",
  "details": [
    {
      "code": "LIMIT_EXCEEDED",
      "message": "Maximum allowed devices has been reached",
      "innerError": {
        "maximumAllowed": 5
      }
    }
  ]
}

Account lockout

The MFA settings property lockout.failureCount and lockout.durationSeconds defines the maximum number of incorrect MFA authorization actions a user can attempt (such as entering an incorrect OTP or denying a push confirmation on a native device) before the account is locked. The lockout.durationSeconds defines the amount of time after the lockout.failureCount value is exceeded to keep the account in a locked state. You can update the setting with PUT {{apiPath}}/environments/{{envID}}/mfaSettings.

For more information about account lockout, refer to User Accounts.

MFA settings data model

Response codes

You can use the PingOne API for various oath token management actions, including creating tokens, revoking tokens, and resyncing tokens.

FIDO policies allow you to fine-tune the use of FIDO2 authentication in authentication flows, for example, by limiting authentication to specific types of FIDO2 devices.

An endpoint (fidoDevicesMetadata) is also provided for reading information from the device metadata table stored by PingOne, and for adding or removing custom devices.

FIDO policies data model

Additional information returned in responses

• id - the ID assigned to the policy
• createdAt
• updatedAt
• _embedded.deviceAuthenticationPolicies - array of the device authentication polices that the FIDO policy is used by. Each object in the array consists of the ID of the device authentication policy and the name of the device authentication policy. Returned only if the query includes the parameter expand=deviceAuthenticationPolicies.

FIDO policies events generated

Refer to Audit Reporting Events for the events generated.

FIDO device metadata

PingOne maintains a global authenticator table, which presents metadata for indvidual authenticators. This includes both authenticators that are represented in the FIDO Alliance Metadata Service (MDS), and custom authenticator data that you add to the table via the UI or the API.

The endpoints provided for FIDO device metadata allow you to:

• Retrieve the basic metadata for all of the authenticators in the table
• Retrieve detailed metadata for a specific authenticator from the table
• Add metadata for custom authenticators
• Delete from the table a custom authenticator that you added

Adding a custom authenticator

When you use the fidoDevicesMetadata endpoint to add a custom authenticator to the global authenticator table, the data included in the request should comform with the Metadata Statement Format provided by the FIDO Alliance.

Before adding an authenticator, using JSON data provided by a manufacturer, verify that it conforms to the following details expected by the PingOne API:

• The metadata outlined in the standard should be enclosed in an object called metadataStatement.
• The metadataStatement should be enclosed in an object that also includes the relevant key identifier: the attestationCertificateKeyIdentifiers array for devices conforming with the U2F protocol, and the aaguid field for devices conforming with the FIDO2 protocol.

Sample body for request - U2F device

{
    "attestationCertificateKeyIdentifiers": [
        "31116a647069d1493f58fc5b54e5449e2a52d43e"
    ],
    "metadataStatement": {
        "legalHeader": "https://fidoalliance.org/metadata/metadata-statement-legal-header/",
        "attestationCertificateKeyIdentifiers": [
            "31116a647069d1493f58fc5b54e5449e2a52d43e"
        ],
        "description": "Yubikey Edge",
        "authenticatorVersion": 1,
        "protocolFamily": "u2f",
        "schema": 3,
        "upv": [
            {
                "major": 1,
                "minor": 1
            }
        ],
        "authenticationAlgorithms": [
            "secp256r1_ecdsa_sha256_raw"
        ],
        "publicKeyAlgAndEncodings": [
            "ecc_x962_raw"
        ],
        "attestationTypes": [
            "basic_full"
        ],
        "userVerificationDetails": [
            [
                {
                    "userVerificationMethod": "presence_internal"
                }
            ]
        ],
        "keyProtection": [
            "hardware",
            "secure_element",
            "remote_handle"
        ],
        "isKeyRestricted": false,
        "isFreshUserVerificationRequired": false,
        "matcherProtection": [
            "on_chip"
        ],
        "cryptoStrength": 128,
        "attachmentHint": [
            "external",
            "wired"
        ],
        "attestationRootCertificates": [
            "MIIDHjCCAgagAwIBAgIEG0BT9zANBgkqhkiG9w0BAQsFADAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDAwMDAwMFowLjEsMCoGA1UEAxMjWXViaWNvIFUyRiBSb290IENBIFNlcmlhbCA0NTcyMDA2MzEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC/jwYuhBVlqaiYWEMsrWFisgJ+PtM91eSrpI4TK7U53mwCIawSDHy8vUmk5N2KAj9abvT9NP5SMS1hQi3usxoYGonXQgfO6ZXyUA9a+KAkqdFnBnlyugSeCOep8EdZFfsaRFtMjkwz5Gcz2Py4vIYvCdMHPtwaz0bVuzneueIEz6TnQjE63Rdt2zbwnebwTG5ZybeWSwbzy+BJ34ZHcUhPAY89yJQXuE0IzMZFcEBbPNRbWECRKgjq//qT9nmDOFVlSRCt2wiqPSzluwn+v+suQEBsUjTGMEd25tKXXTkNW21wIWbxeSyUoTXwLvGS6xlwQSgNpk2qXYwf8iXg7VWZAgMBAAGjQjBAMB0GA1UdDgQWBBQgIvz0bNGJhjgpToksyKpP9xv9oDAPBgNVHRMECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBBjANBgkqhkiG9w0BAQsFAAOCAQEAjvjuOMDSa+JXFCLyBKsycXtBVZsJ4Ue3LbaEsPY4MYN/hIQ5ZM5p7EjfcnMG4CtYkNsfNHc0AhBLdq45rnT87q/6O3vUEtNMafbhU6kthX7Y+9XFN9NpmYxr+ekVY5xOxi8h9JDIgoMP4VB1uS0aunL1IGqrNooL9mmFnL2kLVVee6/VR6C5+KSTCMCWppMuJIZII2v9o4dkoZ8Y7QRjQlLfYzd3qGtKbw7xaF1UsG/5xUb/Btwb2X2g4InpiB/yt/3CpQXpiWX/K4mBvUKiGn05ZsqeY1gx4g0xLBqcU9psmyPzK+Vsgw2jeRQ5JlKDyqE0hebfC1tvFu0CCrJFcw=="
        ],
        "icon": "data:image/png;base64,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"
    }
}

Sample body for request - FIDO2 device

{
    "aaguid": "e1a96183-5016-4f24-b55b-e3ae23614cc6",
    "metadataStatement": {
        "legalHeader": "https://fidoalliance.org/metadata/metadata-statement-legal-header/",
        "aaguid": "e1a96183-5016-4f24-b55b-e3ae23614cc6",
        "description": "ATKey.Pro CTAP2.0",
        "authenticatorVersion": 2,
        "protocolFamily": "fido2",
        "schema": 3,
        "upv": [
            {
                "major": 1,
                "minor": 0
            }
        ],
        "authenticationAlgorithms": [
            "secp256r1_ecdsa_sha256_raw"
        ],
        "publicKeyAlgAndEncodings": [
            "cose"
        ],
        "attestationTypes": [
            "basic_full"
        ],
        "userVerificationDetails": [
            [
                {
                    "userVerificationMethod": "fingerprint_internal",
                    "baDesc": {
                        "selfAttestedFRR": 0,
                        "selfAttestedFAR": 0,
                        "maxTemplates": 0,
                        "maxRetries": 0,
                        "blockSlowdown": 0
                    }
                },
                {
                    "userVerificationMethod": "presence_internal"
                },
                {
                    "userVerificationMethod": "passcode_internal"
                }
            ]
        ],
        "keyProtection": [
            "hardware"
        ],
        "isKeyRestricted": false,
        "isFreshUserVerificationRequired": true,
        "matcherProtection": [
            "on_chip"
        ],
        "attachmentHint": [
            "external"
        ],
        "attestationRootCertificates": [
            "MIIBzDCCAXGgAwIBAgIBATAKBggqhkjOPQQDAjBiMQswCQYDVQQGEwJTRTESMBAGA1UECgwJQVRLZXlDQTAwMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMRswGQYDVQQDExJBdXRoZW50cmVuZCBDQSAwMDAwIBcNMTYwMjI2MDgxMTA2WhgPMjA1MDAyMjUwODExMDZaMGIxCzAJBgNVBAYTAlNFMRIwEAYDVQQKDAlBVEtleUNBMDAxIjAgBgNVBAsMGUF1dGhlbnRpY2F0b3IgQXR0ZXN0YXRpb24xGzAZBgNVBAMTEkF1dGhlbnRyZW5kIENBIDAwMDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAJcWqeCxga9KJbFO2TZdjcgrtZAgfi8TXKu+v5lcR5ceb5GJYxyoCjhueESL3ddmMIkpGyhsEEtfFUyBwsyFVCjFjAUMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0EAwIDSQAwRgIhAPuVS4Pm2KFXdUMi5Pb/Xy+gCROOuRPZ6I57vWc0EvkBAiEA8aRCnXppAffCEOQBJ7vlgwiiHMXA2tpWX+ObvVKxXbM=",
            "MIIBzDCCAXGgAwIBAgIBATAKBggqhkjOPQQDAjBiMQswCQYDVQQGEwJTRTESMBAGA1UECgwJQVRLZXlDQTAwMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMRswGQYDVQQDExJBdXRoZW50cmVuZCBDQSAwMDAwIBcNMTYwMjI2MDgxMTA2WhgPMjA1MDAyMjUwODExMDZaMGIxCzAJBgNVBAYTAlNFMRIwEAYDVQQKDAlBVEtleUNBMDAxIjAgBgNVBAsMGUF1dGhlbnRpY2F0b3IgQXR0ZXN0YXRpb24xGzAZBgNVBAMTEkF1dGhlbnRyZW5kIENBIDAwMDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAJcWqeCxga9KJbFO2TZdjcgrtZAgfi8TXKu+v5lcR5ceb5GJYxyoCjhueESL3ddmMIkpGyhsEEtfFUyBwsyFVCjFjAUMBIGA1UdEwEB/wQIMAYBAQECAQAwCgYIKoZIzj0EAwIDSQAwRgIhAMqIc/Qtr+jZbnrJB7g7W8r/DHmDe+IyFvzwpzdSrxEXAiEAtXcixZznhcDzlnIqFqkIJRGmvL9Yr6lVoP1ZkDeqmjk="
        ],
        "icon": "data:image/png;base64,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",
        "authenticatorGetInfo": {
            "versions": [
                "U2F_V2",
                "FIDO_2_0",
                "FIDO_2_1_PRE"
            ],
            "extensions": [
                "credBlob",
                "credProtect",
                "hmac-secret"
            ],
            "aaguid": "e1a9618350164f24b55be3ae23614cc6",
            "options": {
                "uv": true,
                "userVerificationMgmtPreview": true,
                "credMgmt": true,
                "uvBioEnroll": true,
                "rk": true,
                "plat": false,
                "clientPin": false,
                "up": true,
                "bioEnroll": true,
                "credentialMgmtPreview": true
            },
            "maxMsgSize": 2048,
            "pinUvAuthProtocols": [
                1
            ],
            "maxCredentialCountInList": 20,
            "maxCredentialIdLength": 128,
            "transports": [
                "usb"
            ],
            "algorithms": [
                {
                    "type": "public-key",
                    "alg": -7
                },
                {
                    "type": "public-key",
                    "alg": -8
                }
            ],
            "firmwareVersion": 10013
        }
    }
}

To reduce the friction of frequent authentication requests, your MFA policies can allow the use of a "remember me" option. When you enable this option, you specify the maximum time a device can be remembered. During this period, if a user tries to access applications from the same computer and browser, they will not be asked for further authentication.

The use of this feature requires the following elements:

• Embedding the Signals SDK in the UI of your application.
• Adding a "remember me" option to the UI of your application.
• Enabling the "remember me" option in the MFA policies that you plan on using.
• Sending an API request with the relevant information so that the user's browser is recorded as a remembered device.
• When the user subsequently tries to access an application, sending the API request that compares the current browser information with the information that was recorded previously.

Creating a remembered device

To create a remembered device:

1. Get the ID of the MFA policy that is being used.
2. Get the details of the MFA policy.
3. Check the content of the rememberMe object in the MFA policy to see if the "remember me" option can be used with this policy (rememberMe.web.enabled).
4. If "remember me" is enabled, send a request using the devices endpoint, as shown in the Create Remember Me Device example.
5. The response to the request will include a cookie in the set-cookie header. When it comes time to check if a device is remembered, you will have to include this cookie in the headers for the request.

Checking if device is recognized

To check if a user is using a remembered device:

1. Get the ID of the MFA policy that is being used.
2. Get the details of the MFA policy.
3. Check the content of the rememberMe object in the MFA policy to see if the "remember me" option can be used with this policy (ememberMe.web.enabled).
4. If "remember me" is enabled, send a request using the deviceAuthentications endpoint and the application/vnd.pingidentity.payload.check+json header, as shown in the Check if Device Remembered example. The headers must also include the cookie that was returned when the remembered device was created. Note that if you included the PingOne session ID by using the optional session.id parameter when creating the remembered device, you must include the deviceSession.id parameter when checking if the device is remembered.

Create Remembered Device data model

Check Remembered Device data model

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.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.

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

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.

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

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.
PingOne MFA	Postman requests for the PingOne MFA API. Includes all PingOne Platform API Reference documentation and example responses. 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 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: