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}}/v1/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.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

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.

Pairing key errors

In addition to the general error codes, pairing key operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /pairingKeys request references an application that does not exist or is not available for pairing, references an application that is not in the configured device authentication policy, or names applications when the policy does not allow pairing for them

Details: Couldn’t find available applications for pairing when no pairable applications exist in the environment, with no target and no inner error, One or more of the provided applications were not found or not available for pairing for an unknown application ID, One or more of the provided applications were not found in the configured auth method policy for an application outside the policy, or Applications were not found in the MFA policy, policyId = <policyId> when the policy’s mobile section is disabled or has no applications, or One or more of the provided applications are not available for pairing in the configured auth method policy for an application with pairing disabled. The second and third messages have target applications and an allowedValues inner error listing the pairable application IDs, and the last two have target applications with no inner error.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /pairingKeys request supplies a mobilePayload without platform authorization or a policy without environment-level authorization

Details: Invalid value for attribute with target mobilePayload or policy and an allowedValues inner error

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: A resource with the specified name already exists.

When and details

When: A POST /pairingKeys request auto-enrolls a mobile payload device that is already paired

Details: device already exists with target device and an inner error containing existingId and actual

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /pairingKeys request conflicts with an existing unclaimed pairing key (an intersecting but different application set)

Details: is unique but a non-unique value is provided with target applications

400

REQUEST_LIMITED

LIMIT_EXCEEDED

Message: The request could not be completed. A rate or quota limit was reached. Please try again later.

When and details

When: A POST /pairingKeys request creates a pairing key when the per-user pairing key limit (20 in the documented default case) is already reached

Details: Maximum pairing keys allowed per user had reached the limit of: <limit> with target pairingKey

403

ACCESS_FAILED

None

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The actor lacks the mfa:create:pairingKey permission (POST), the mfa:read:pairingKey permission (GET), or the mfa:delete:pairingKey permission (DELETE), or is not the target user or a delegated administrator for a self-service token

Details: None

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET or DELETE /pairingKeys operation references a pairing key that does not exist, or GET/POST references a user that does not exist in the environment

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The pairing process fails with an internal error while finalizing the device pairing

Details: None