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 /environments/{environmentId}/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. See 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. See PingOne MFA SDK for Android or PingOne SDK for iOS.

Pairing key data model

Property Description
_links.self The URL of the pairing key resource.
_links.environment The URL of the environment resource.
_links.user The URL of the user resource.
id The resource ID.
environment.id The environment ID.
code The pairing key that the end users should use for pairing their device.
status The status of the pairing key. Valid values:
  • UNCLAIMED
  • CLAIMED
  • FAILED
error.code A string specifying the code indicating the reason that status is FAILED.
error.message A string containing the message indicating the reason that status is FAILED.
applications The collection of application IDs that can be used with this pairing key.
user.id The user ID.
createdAt The date this pairing key was created.
updatedAt The date this pairing key was updated.
expiresAt 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.