Authenticate with Voice


This page is an extension of the regular Authentication API: Start a new authentication (POST). However, in this case, usage of voice for authentication requires special considerations, which involve additional fields.

Request parameters

Parameter Description
payload The payload returned from an authentication request which originated from a mobile application which is integrated with PingID SDK.
locale

The international locale for voice configuration.

  • Optional.
  • Default is "en_US".

voiceMessage

The voice authentication message.

    The voice message which is sent in order to authenticate a user.

    • Mandatory, when the authenticating device is voice.
    • Used only if the authenticating device is voice.

    Refer to Offline devices (voice) pairing API for details and examples of message usage.

voiceVendor

The name of the message service supplier.

  • Optional.
  • Currently, "Twilio" (default) is supported.

voice

Vendor specific supported voices.

Currently supported Twilio voices:

  • Alice (default)
    Supported locales (default: en_US):
    da_DK, de_DE, en_AU, en_CA, en_GB, en_IN, en_US, ca_ES, es_ES, es_MX, fi_FI, fr_CA, fr_FR, it_IT, ja_JP, ko_KR, nb_NO, nl_NL, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, zh_CN, zh_HK, zh_TW
  • Man, Woman
    Supported locales (default: en):
    en, en_GB, es, fr, de
voiceParameters

User defined parameters, for the purpose of embedding application values into the voice message.

  • Optional.

You can define any application parameters, except for ${otp} or parameters starting with ${pingid_}

Authenticate using voice, without payload (POST)

This section focuses on the scenarios where the authenticating device is a voice device.

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

  • The authentication request contains the device ID which is known to be a voice device.
  • The authentication request does not contain the device ID, and it is possible that the authenticating device will be a voice 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

{ 
  "voiceMessage""Your authentication code is: ${OTP}", \
  "voiceVendor""Twilio", \
  "locale""en_US", \
  "voiceParameters": {}, \
  "voice""Alice" 
}

Authentication using the additional voice fields

Voice authentication request body

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \
   "voiceMessage": "Your authentication code is: ${OTP}", \
   "voiceVendor": "Twilio", \
   "locale": "en_US", \
   "voiceParameters": {}, \
   "voice": "Alice" \
 }' 'https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6/users/user1/authentications'

Voice authentication response

{
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6/users/or1/authentications/webs_c8c26de3-25bf-4fbe-8f64-03f96e9e64e0"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/users/or1"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d"
  },
  "id": "webs_c8c26de3-25bf-4fbe-8f64-03f96e9e64e0",
  "deviceId": "1b2a61e7-ff6f-407d-1b2a-61e7ff6f407d",
  "status": "OTP",
  "device": {
    "deviceType": "Voice",
    "id": "1b2a61e7-ff6f-407d-1b2a-61e7ff6f407d",
    "deviceName": null,
    "deviceNickname": "User1 Voice",
    "deviceFingerprint": "12025556666",
    "deviceRole": "primary",
    "enrollmentTime": 1528202193730,
    "applicationId": "dad9528a-f889-4b90-9300-b929d995a2b6",
    "bypassExpiration": null,
    "bypassed": false,
    "phoneNumber": "37500638",
    "emailAddress": null,
    "countryCode": "972",
    "pushEnabled": false,
    "osVersion": null,
    "applicationVersion": null,
    "deviceStatus": "ACTIVE"
  },
  "requiredLevel": "PUSH",
  "level": "NONE",
  "payload": "",
  "enableGetPayloadResponseMobileApi": false
}

Finalizing voice authentication

When the authenticating device is a voice device, the authentication must be finalized.

The PUT method using the otp parameter with the OTP value returned by the user finalizes authentication, and the id of this authentication, which was initiated in the previous step (POST).

Relative Path

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

Request body structure

Use the following request body structure to finalize authentication:

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

Voice 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'

Voice authentication finalization response example

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

Voice authentication with SDK payload

Any authentication request which originates from a mobile application that is integrated with PingID SDK must 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 voice device, the message parameter in the authentication request may also contain the accessing device’s name and device type.

Voice authentication structure example, when the request contains SDK payload

Authentication using the additional voice fields

Additional fields in the authentication request body structure

{ 
  “payload”: “<payload from the mobile application>”, \
  "voiceMessage""Your authentication code is: ${OTP}", \
  "voiceVendor""Twilio", \
  "locale""en_US", \
  "voiceParameters": {}, \
  "voice""Alice" 
}

Voice authentication request body

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \
   "payload": "", \
   "voiceMessage": "Your authentication code is: ${OTP}", \
   "voiceVendor": "Twilio", \
   "locale": "en_US", \
   "voiceParameters": {}, \
   "voice": "Alice" \
 }' 'https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6/users/user1/authentications'