Orchestration SDKs

Pairing with a QR code or pairing key on iOS

PingOne iOS

You can pair a device directly, without the device itself having to run a DaVinci flow.

A DaVinci flow still plays a part, but it runs on the accessing device only. That flow creates the pairing key, and your app pairs out-of-band using the key as its input, either as a QR code that the user scans, or as text that the user enters manually.

For example, the accessing device’s sign-on screen displays a QR code for the user to scan with their phone.

To register a device with PingOne MFA manually, call the pingonemfa module’s pair function, providing the pairing key as its only parameter.

The device must be able to reach the PingOne MFA service over the network to pair.

After pairing, the device can generate OATH one-time passcodes in isolation on the device, so they keep working without connectivity.

Push notifications, however, always need connectivity, because the notification has to travel from the PingOne MFA service to the device.

Getting the pairing key

The pairing key comes from your PingOne environment, typically displayed on the accessing device as part of the sign-on flow.

The key can be rendered as a QR code for the user to scan, or shown as text for them to type into your app.

For example, in a DaVinci flow being run on the primary device, you could use the Form connector’s Show Form capability with a form that has a QR Code form field on it, containing the code value from the PingOne MFA connector’s Create Pairing Key capability.

Pairing the device

Ensure that you have initialized the PingOneMFA module before attempting to pair the device. Learn more in Setting up the pingonemfa module on iOS.

Then, after obtaining the pairing key, call pair(pairingKey:).

The function is async throws.

Pairing with a pairing key
import PingOneMFA

// Initialize the module
do {
    try await PingOneMFA.initialize(geo: .northAmerica)

    // Obtain the pairing key, for example by decoding a scanned QR code
    // or reading the user-entered text
    let pairingKey = getPairingKey()

    try await PingOneMFA.pair(pairingKey: pairingKey)
    // Pairing succeeded — update UI as needed
} catch {
    print("Pairing failed: \(error.localizedDescription)")
}

After pairing succeeds, the device is registered with the PingOne MFA service. The app can now respond to push notifications and generate one-time passcodes.

Error handling

If pairing fails, the error objects returned by the module carry a human-readable message and structured details for logging. See Error handling and troubleshooting.