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.
Pair an email device to a user (POST)
The POST method is used in order to pair a user with an email device.
Relative Path
/accounts/{accountId}/applications/{applicationId}/users/{username}/emailpairings
Request body structure
{
"automaticPairing": <true or false>,
"deviceNickname": "<the device nickname>",
"locale": "<the email configuration locale>",
"type": "<the email configuration type>",
"recipient": "<email address>",
"emailParameters": <parameters map>
}
Request parameters
Parameter | Description |
---|---|
automaticPairing |
Determine whether the pairing is automatic or manual.
Valid values:
|
deviceNickname |
It is possible to name the device in this request.
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.
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.
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.
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.
You can define placeholders for the email subject line and body, which will be substituted by mapped values when the email is sent.
For example, if the template comprises the following: Hi ${username}! do you want to transfer ${transfer}? To confirm please use OTP:${otp} "emailParameters": {"transfer":"1000$;", "username": "user1"} Hi user1! do you want to transfer 1000$? To confirm please use OTP:123456
|
Automatic pairing example
Automatic pairing request body
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' \
-d '{ \
"recipient": "user@example.com", \
"automaticPairing": true, \
"deviceNickname": "User1 Email Device" \
}' 'https:// sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/emailpairings'
Automatic pairing response
{
"automaticPairing": true,
"deviceType": "EMAIL",
"id": "pairing_webs_92642fda-ba99-41c7-8ba7-0a0f980cd8d6",
"deviceNickname": "User1 Email Device",
"recipient": "user@example.com"
}
Manual pairing example
Manual pairing request body
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' \
-d '{ \
"recipient": "user@example.com", \
"automaticPairing": false, \
"deviceNickname": "User1 Email Device", \
"locale": "en", \
"type": "pairing", \
"emailParameters": {"transfer": "1000", "greeting": "Good Evening"} \
}' 'https:// sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/
emailpairings'
Manual pairing response
{
"id": "pairing_webs_5dca4cfb-257c-4f90-a31f-eb18d9c992e2",
"automaticPairing": false,
"deviceType": "EMAIL",
"deviceNickname": "User1 Email Device",
"locale": "en",
"type": "pairing",
"emailParameters": {"transfer": "1000", "greeting": "Good Evening"}
}
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
/accounts/{accountId}/applications/{applicationId}/users/{username}/emailpairings/{pairingId}/otp
Request body structure
Use the following request body structure:
{
"otp": "<the OTP>",
"deviceNickname": "<device nickname>"
}
Request parameters
Parameter | Description |
---|---|
deviceNickname |
It is possible to name the device in this request. Optional. 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. |
otp |
The value of the OTP received from the user. |
Manual pairing finalizing request example
curl -X PUT \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' \
-d '{ \
"otp": "172358", \
"deviceNickname": "Email Device 1" \
}' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/emailpairings/pairing_webs_5dca4cfb-257c-4f90-a31f-eb18d9c992e2/otp'
Entering an incorrect OTP returns an error response, for example:
{
"message": "Couldn’t pair user",
"details": [
{
"message": "Invalid passcode",
"target": "otp",
"code": "INVALID_VALUE"
}
],
"code": "REQUEST_FAILED"
}
Entering 3 incorrect OTPs in succession terminates the pairing process, results in the deletion of the pairing resource, and returns an error response, for example:
{
"message": "Couldn’t pair user",
"details": [
{
"message": "Exceeded max passcode retry limit" ,
"target": "otp",
"code": "RETRY_LIMIT_EXCEEDED"
}
],
"code": "REQUEST_FAILED"
}
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.
Relative Path
/accounts/{accountId}/applications/{applicationId}/users/{username}/emailpairings/{pairingId}
Pairing resource read request example
curl -X GET \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' 'https://sdk.pingid.com/
pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/
applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/emailpairings/
pairing_webs_efa2d50f-2e2d-435e-be62-23b86dae73dc'
Pairing resource read request response example
{
“locale”: “en”,
“type”: “authentication”,
“recipient”: “user@example.com”,
“automaticPairing”: false,
“id”: “pairing_webs_efa2d50f-2e2d-435e-be62-23b86dae73dc”,
“deviceType”: “EMAIL”,
“emailParameters”: {“transfer”: “1000”, “greeting”: “Good Evening”}
}
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.
Use the DELETE method to cancel a manual pairing process.
Relative Path
/accounts/{accountId}/applications/{applicationId}/users/{username}/emailpairings/{pairingId}
Pairing resource deletion request example
curl -X DELETE \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' \
'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user4/
emailpairings/pairing_webs_db78f5fd-ddad-45fd-921f-d3f59fd1b28e'