Authenticate with Email

This page is an extension of the regular Authentication API: Start a new authentication (POST). However, in this case, usage of email for authentication requires special considerations, which are the 3 additional fields locale, emailConfigurationType and emailParameters.

In order for email pairing and authentication to take place:

  • Email pairing and authentication must be enabled for the application.
  • Email templates must be configured.

Authenticate using email, without payload (POST)

This section focuses on the scenarios where the authenticating device is an email device.

The authenticating device is an email device in one of the following cases:

  • The authentication request contains the device ID which is known to be an email device.
  • The authentication request does not contain the device ID, and it is possible that the authenticating device will be an email device.

The following examples deal with scenarios in which an authentication request does not contain a mobile application payload.

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/authentications

Additional fields in the authentication request body structure

{
  "locale": "en",
  "emailConfigurationType": "authentication_type1",
  "emailParameters": {"transfer": "1000$", "product": "book"}

}

Request parameters

Parameter Description
locale

The international locale for email configuration.

  • Optional.
  • Default is "en"

PingID SDK retrieves the email configuration which corresponds with the "locale" and "emailConfigurationType" 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.

emailConfigurationType

The email configuration type.

  • Mandatory.

PingID SDK retrieves the email configuration which corresponds with the "locale" and "emailConfigurationType" 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

Authentication using the additional email fields (POST)

Email authentication request body

curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMC=<JWT>' \
-d '{ \
     "deviceId": "16e77acb-10ef-4588-16e7-7acb10ef4588", \
     "mailConfigurationType": "111" \
}' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user4/
authentications'

Email authentication response

{
  "id": "webs_9e5f9757-623d-490d-9615-2a5a6a351a0b",
  "deviceId": "16e77acb-10ef-4588-16e7-7acb10ef4588",
  "status": "OTP",
  "requiredLevel": "PUSH",
  "level": "NONE",
  "payload": ""
}

If the email template is not configured, the following error message will be produced:

{
  "message": "Couldn’t authenticate",
  "details": [
      {
        "message": "Email template doesn't exist for [type=111] [locale=en]",
        "code": "NOT_FOUND"
      }
   ],
  "code": "REQUEST_FAILED"
}

Finalizing email authentication (PUT)

When the authenticating device is an email device, the authentication must be finalized.

The PUT method using the otp parameter with the OTP value returned by the user finalizes authentication.

Request body structure

Use the following request body structure to finalize authentication:

{
  "otp": "<the OTP from the user>",
}
`

Email authentication finalization request body example

curl -X PUT \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMC=<JWT>' \
-d '{ \
        "otp": "363451" \
    }' 'https:// sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/
authentications/webs_4259429a-8fb2-438c-8897-c205f188f4a3/otp'

Email authentication finalization response example

{  
"id": "webs_4259429a-8fb2-438c-8897-c205f188f4a3",  
"status": "APPROVED",   
"deviceId": "6086deb9-def7-bfc2-6086-deb9def7bfc2",   
"requiredLevel": "PUSH",   
"level": "OTP",  
 "payload": "" 
}

Email authentication with SDK payload (POST)

Any authentication request which originates from a mobile application that is integrated with PingID SDK should always contain the SDK payload.

If an application with SDK integration on an unpaired mobile device issues an authentication request to an active user who has at least one paired device, the user’s primary or selected device must approve authentication to the unpaired device.

When the approving device is an email device, the configured email subject or email body text may contain the requesting device’s device_type and device_name parameters in the authenticating request.

In addition to the locale, emailParameters and emailConfigurationType parameters which are always used for authentication, the payload parameter must be provided with the payload value returned from the mobile application.

Email authentication structure example, when the request contains SDK payload

curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMC=<JWT>' -d '{ \
    "payload": "<payload from the mobile application>", \
    "locale": "de", \
    "emailConfigurationType": "authentication_with_payload", \
    "emailParameters": {"transfer": "1000", "product": "book"} \
  }' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-
d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user4/
authentications'