PingOne Platform APIs

MFA Pairing Keys

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.

By default, pairing keys are valid for 10 minutes. You can have a maximum of 20 valid pairing keys per user at any given time.

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

Property Type Required? Mutable? Description

id

String

N/A

Read-only

The resource ID.

environment.id

String

N/A

Read-only

The environment ID.

code

String

N/A

Read-only

The pairing key that the end users should use for pairing their device.

status

String

N/A

Read-only

The status of the pairing key. Valid values:

* UNCLAIMED

* CLAIMED

* FAILED

error.code

String

N/A

Read-only

The code indicating the reason that status is FAILED.

error.message

String

N/A

Read-only

The message indicating the reason that status is FAILED.

applications

String[Array]

Optional

Mutable

The collection of application IDs that can be used with this pairing key.

user.id

String

N/A

Read-only

The user ID.

policy.id

String

Optional

Mutable

A string that specifies the device authentication policy ID associated with the pairing key resource. Specifying a device authentication policy ID applies that policy on the API, which determines the MFA methods and mobile applications that are allowed. This property is not returned with GET operations. Currently, if a policy ID is not specified on the request, the environment policy is used. However, this behavior is temporary; it is highly recommended that you specify a policy ID in the POST operation request body.

createdAt

Date

N/A

Read-only

The date this pairing key was created.

updatedAt

Date

N/A

Read-only

The date this pairing key was last updated.

expiresAt

Date

N/A

Read-only

The date this pairing key expires.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

500

Unexpected server error.