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

Authenticate using SMS, without payload (POST)

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

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

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

{
  "smsMessage": "<sms authentication message>",
  "smsSender": "<the sms sender>"
}

Request parameters

Parameter	Description
smsMessage	The SMS message. Mandatory, when the authenticating device is an SMS device, or when the authenticating device type is not known in advance. The message may be empty only when the authenticating device is not an SMS device, for example when the request specifies a device id known to be other than SMS. If the SMS message is missing and the authenticating device is an SMS device, an error is returned. The OTP is generated in the PingID SDK server, and sent in this message. The ${otp} parameter may optionally be used in the message to embed the OTP value in a specific position of the message, for example, "Your authentication code is: ${otp}". The value of ${otp} is dynamically populated at message transmission time. The ${otp} parameter is not case sensitive, and may be used multiple times in the message. If the ${otp} parameter is not used in the message, the message will be appended with one space and the value of the OTP. The message may not exceed 160 characters, including the trailing space and 6 characters of the OTP. Attempts to send a message which exceeds this limit will result in an error. The message may be sent in any language.
smsSender	The sender ID of the SMS message. Optional, only if the authenticating device is SMS. If the sender ID is specified: Only numbers, English characters and spaces are allowed. Length may be up to a maximum of 11 characters. Default Ping Identity and custom Twilio sender accounts: By default, Ping Identity uses Twilio as the SMS and Voice provider. In some countries, including the US, it is impossible to send an SMS with an alphanumeric sender ID. For those countries, the sender ID must be empty. For International alphanumeric sender support, please refer to https://support.twilio.com/hc/en-us/articles/223133767-International-support-for-Alphanumeric-Sender-ID. If the sender field is empty, the SMS sender will be an arbitrary PingID phone number, except for India. If the SMS recipient is located in India, the sender will appear as "PingID", which is the required registered sender ID in India. Custom Syniverse sender accounts: In cases where Syniverse is the SMS and Voice provider, your organization should purchase a specific alpha shortcode and also configure an alias for a specific senderId. See Syniverse's article https://sdcsupport.syniverse.com/hc/en-us/articles/115002280774-Sender-ID-Auto-Alias-Purchase-Number-Masking- for more details.

Parameter

Description

smsMessage

The SMS message.

Mandatory, when the authenticating device is an SMS device, or when the authenticating device type is not known in advance.
The message may be empty only when the authenticating device is not an SMS device, for example when the request specifies a device id known to be other than SMS. If the SMS message is missing and the authenticating device is an SMS device, an error is returned.
The OTP is generated in the PingID SDK server, and sent in this message.
The ${otp} parameter may optionally be used in the message to embed the OTP value in a specific position of the message, for example, "Your authentication code is: ${otp}". The value of ${otp} is dynamically populated at message transmission time.
The ${otp} parameter is not case sensitive, and may be used multiple times in the message.
If the ${otp} parameter is not used in the message, the message will be appended with one space and the value of the OTP.
The message may not exceed 160 characters, including the trailing space and 6 characters of the OTP. Attempts to send a message which exceeds this limit will result in an error.
The message may be sent in any language.

smsSender

The sender ID of the SMS message.

Optional, only if the authenticating device is SMS.

If the sender ID is specified:

Only numbers, English characters and spaces are allowed.

Length may be up to a maximum of 11 characters.

Default Ping Identity and custom Twilio sender accounts:
By default, Ping Identity uses Twilio as the SMS and Voice provider.
In some countries, including the US, it is impossible to send an SMS with an alphanumeric sender ID. For those countries, the sender ID must be empty. For International alphanumeric sender support, please refer to https://support.twilio.com/hc/en-us/articles/223133767-International-support-for-Alphanumeric-Sender-ID.
If the sender field is empty, the SMS sender will be an arbitrary PingID phone number, except for India. If the SMS recipient is located in India, the sender will appear as "PingID", which is the required registered sender ID in India.
Custom Syniverse sender accounts:
In cases where Syniverse is the SMS and Voice provider, your organization should purchase a specific alpha shortcode and also configure an alias for a specific senderId. See Syniverse's article https://sdcsupport.syniverse.com/hc/en-us/articles/115002280774-Sender-ID-Auto-Alias-Purchase-Number-Masking- for more details.

Authentication using the additional SMS fields

SMS authentication request body

Some countries require the SMS sender ID (smsSender) to be empty, as shown in this example:

curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' \
-d '{ \
     "smsMessage": "Your authentication is code: ${otp}", \
     "smsSender": "" \
}' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/authentications'

SMS authentication response

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

Finalizing SMS authentication

When the authenticating device is an SMS 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>",
}

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

SMS authentication finalization response example

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

SMS 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 SMS device, the smsMessage parameter in the authentication request may also contain the accessing device’s name and device type.

SMS authentication structure example, when the request contains SDK payload

{
  "payload": "<payload from the mobile application>",
  "smsMessage": "New device access: ${device_name} ${device_type}. If you approve, use the code: ${otp}",
  "smsSender": "<the sms sender ID>"
}

Parameter	Description
payload	The payload returned from the mobile application with SDK integration.
smsMessage	The SMS message. Mandatory when the authenticating device is an SMS device. The message may include up to 160 characters. The message may be sent in any language. May contain the parameters device_name and device_type. The device_name and device_type parameters are case insensitive, and can appear more than once in the message. The device_name and device_type parameters are optional, and usage of one does not require the other to be specified. It is recommended as best practice to have them both in the message, so that the user knows which unpaired device is trying to authenticate. The message may be empty only if the authenticating device is not an SMS device, for example when the request specifies a device id, and that device is known to be other than SMS. If the SMS message is missing and the authenticating device is an SMS device, an error is returned. The OTP is generated in the PingID SDK server, and sent in this message. The ${otp} parameter may optionally be used in the message to embed the OTP value in a specific position of the message. The value of ${otp} is dynamically populated at message transmission time. The ${otp} parameter is not case sensitive, and may be used multiple times in the message. If the ${otp} parameter is not used in the message, the message will be appended with one space and the value of the OTP. The message may not exceed 160 characters, including parameters values the trailing space and 6 characters of the OTP. Attempts to send a message which exceeds this limit will result in an error. A message that contains the device_name and device_type parameters alerting the user that a new device is attempting access, is relevant only when the request contains the SDK payload. When there is no SDK payload, the message will include the parameters as is. If the request does not contain the SDK payload, the SMS message can only be used for user authentication with SMS. An example of such a message may be: Your authentication code is: ${otp}. The SMS message cannot be empty if it is sent to a paired SMS device for a new device approval. Therefore, if it is not known in advance which device will be used for authentication, the recommended best practice is to include an SMS message.
smsSender	The sender ID of the SMS message. This parameter is optional, and is the same as when authenticating without a payload. If the sender ID is specified: Only numbers, English characters and spaces are allowed. Length may be up to a maximum of 11 characters. In some countries, including the US, it is impossible to send an SMS with an alphanumeric sender ID. For those countries, the sender ID must be empty. For international alphanumeric sender support, please refer to https://support.twilio.com/hc/en-us/articles/223133767-International-support-for-Alphanumeric-Sender-ID. If the sender field is empty, the SMS sender will be an arbitrary PingID phone number, except for India. If the SMS recipient is located in India, the sender will appear as "PingID", which is the required registered sender ID in India.

Parameter

Description

payload

The payload returned from the mobile application with SDK integration.