Platform APIs
More PingIdentity APIs

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.

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.

  • Optional.

Valid values:

  • True: The user will be automatically paired
  • 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".
    • Protected (reserved) placeholders: "otp", "device_name", "device_type", anything with the prefix "pingid_"
  • Value validation: none.
  • The email body size after all placeholders are replaced should be 100 KB or less.
  • The email subject line after all placeholders are replaced should contain 256 characters or less.
  • Placeholders are substituted in alphabetic sequence.

For example, if the template comprises the following: 

Hi ${username}! do you want to transfer ${transfer}? 
To confirm please use OTP:${otp}
and emailParameters is defined as: 
"emailParameters": {"transfer":"1000$;", "username": "user1"}
the user will receive the following mail text: 
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'