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.
A user cannot create a native (mobile) device with POST /environments/{{envID}}/users/{{userID}}/devices. The user must create the device with a pairing key:
The user installs a native app with an embedded PingOne MFA Native SDK component.
The user starts an MFA authentication flow and creates a pairing key. See Multi-factor MFA Action in the Developer Guide for more information.
The user scans the pairing key QR code with the native app.
The embedded PingOne MFA Native SDK starts the pairing process where the device resource is created. See PingOne MFA SDK for Android or PingOne SDK for iOS.
| 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:
|
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. |
| 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. |