Verify phone using SMS OTP

Overview

One-time passcodes can be sent to users by SMS in order to verify their phone number. For example, this can be used to enrich the profile of existing users that are already logged in. Once the SMS passcode is validated, the phone number will be added to the user profile and marked as verified. Unlike the authentication flows, users will not be authenticated (or created) and no tokens will be returned.

Step 1: Send SMS passcodes

Use a send request like the one below to send an SMS OTP to the specified phone number. This flow is described in the sequence diagram above.

Note

This flow requires an existing, logged-in user. So make sure you have a valid user access token (returned upon successful authentication) to authorize the request.

Copy

Copied

curl --request POST \
     --url https://api.userid.security/v1/verification/otp/sms/send \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 91827321837bdfjf' \
     --header 'Content-Type: application/json' \
     --data '
{
     "phone_number": "+15125555555"
}
'

Step 2: Validate SMS passcodes

Validate the SMS OTP entered by the user using a validation request like the one below. Once validated, the phone number will be added to the user profile and marked as verified. Since this flow is intended for existing users that are logged in, the user won't be authenticated (or created) and no tokens will be returned. This flow is described in the sequence diagram above.

Copy

Copied

curl --request POST \
     --url https://api.userid.security/v1/verification/otp/sms/validate \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 91827321837bdfjf' \
     --header 'Content-Type: application/json' \
     --data '
{
     "passcode": "123456",
     "phone_number": "+15125555555"
}
'

Next steps

Once you've completed a basic integration, here are some customizations you can consider:

Code expiration
Custom SMS provider

OTP settings

In the Admin Portal, you can configure the expiry time for the codes sent in SMS messages. From the top of the Authentication page, select the required application from the drop-down list. From the One-time passcodes settings, in the Expires in textbox, enter the number of minutes after which OTPs expire.

Custom SMS provider

In the Admin Portal (from Settings > SMS Provider), you can configure to use Twilio as your SMS provider instead of the Transmit default. For example, this allows you to customize the sender name per country. For more, see Use custom SMS providers.