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	Deprecated.
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 Currently supported Syniverse voices: Supported locales (default: en_US): en_US, en_GB, es_ES, fr_FR, de_DE, it_IT Syniverse's default voices are used, based on locale and gender. Using Alice and Woman in the API are interpreted as Female in Syniverse. Using Man in the API is interpreted as Male in Syniverse. Priority is given first to locale (en_US is default), and then gender (Female is default).
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}", \
  "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}", \
   "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).

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.

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

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}", \
  "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}", \
   "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'

Authenticate with Voice

Authenticate using voice, without payload (POST)

Authentication using the additional voice fields

Finalizing voice authentication

Voice authentication with SDK payload

Authentication using the additional voice fields