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 must be enabled as an authentication method for the application.
• To use your organization’s own trusted email domains and email addresses for email notifications, you must configure Trusted email domains and Trusted email addresses.
• Email templates must be configured.

If the user enters an invalid OTP 3 times in succession, the pairing or authentication process fails.

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

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

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-HMAC=<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.

The session becomes invalid after successful authentication has completed. If there is an attempt to reuse the same OTP in the same user authentication session, it will be rejected.

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-HMAC=<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": "" 
}

Authenticate using email, with 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-HMAC=<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'