Offline devices (email) pairing API

An email address is regarded by PingID as a device for pairing and authentication purposes. A device may be paired with a user, only in the context of an application. As a prerequisite, the user and application must be created before device pairing can take place. Email authentication should be enabled in the admin console. For configuration details, please refer to Manage PingID SDK applications in the PingID administrator guide.

False (default): After making this call, the authentication must be finalized using the OTP received from the user, who in turn, received it in the email message.

deviceNickname

It is possible to name the device in this request.

Optional.

The device nickname must not exceed 100 characters and can be in any language.

If the device nickname is empty, the PingID SDK service will name the device “Email 1” (or “Email 2”, “Email n” etc., incrementing the trailing digit depending on the number of email devices for that user).

locale

The international locale for email configuration.

Optional.

Default is "en".

Ignored in automatic pairing.

In manual pairing, PingID SDK retrieves the email configuration which corresponds with the "locale" and "type" parameters specified in the request. The ${otp} parameter in the email configuration is replaced by the
OTP value, and then the email is sent to the recipient.

type

The email configuration type.

Mandatory for manual pairing.

Ignored in automatic pairing.

In manual pairing, PingID SDK retrieves the email configuration which corresponds with the "locale" and "type" parameters specified in the request. The ${otp} parameter in the email configuration is replaced by the
OTP value, and then the email is sent to the recipient.

recipient

The email address to be paired.

Mandatory.

Must be a valid email address.

In manual pairing, PingID SDK retrieves the email configuration which corresponds with the "locale" and "type" parameters specified in the request. The ${otp} parameter in the email configuration is replaced by the
OTP value, and then the email is sent to the recipient.

emailParameters

Customized placeholders for email templates.

Optional.

You can define placeholders for the email subject line and body, which will be substituted by mapped values when the email is sent.

Key validation: alphanumerics, dashes and underscores. An error is sent if the key is a "protected placeholder".

Finalizing manual pairing

The POST method using the "automaticPairing": true parameter completes automatic pairing. However, manual pairing requires an additional finalizing step to reach completion.
Any attempt to finalize pairing with OTP when the device was automatically paired, results with an error.
In order to finalize manual pairing, you must update the pairing resource with the OTP received from the user.
Once you receive the OTP from the user, you can finalize the pairing process by using the PUT method to call the URL in the following relative path:
Relative Path

If the device was already named, renaming it at this stage overrides the previous device
nickname.

If the device was not previously named, the PingID SDK service will name the device
“Email 1” (or “Email 2”, “Email n” etc., incrementing the trailing digit depending on the
number of email devices for that user).

If the device nickname is empty or missing, and the device was named when creating the
pairing resource, the device name remains unchanged.

The device nickname must not exceed 100 characters and can be in any language.

Read an email pairing resource (GET)

When a pairing process is invoked, a temporary pairing resource is created, which has a maximum lifetime of 30 minutes. The pairing resource is automatically deleted after successful completion of pairing, and in the case of a failure following entry of 3 incorrect OTPs.
While the pairing resource exists, the GET method may be used in order to read it.

Delete an email pairing resource (DELETE)

If a pairing process is manual, it is possible to cancel the process by deleting the temporary pairing resource which was created at its inception.
However, deletion of the temporary pairing resource for an automatic pairing process will not unpair the device.