Skip to main content

Authenticate transactions with SMS

If your phone number is registered, you can use an mTAN as a second factor to authenticate a transaction. For example, after processing the usual username and password at login, you send a text message with a one-time code to the user's mobile phone to provide a second factor for authentication.

The following diagram shows the end-to-end sequence of an SMS authentication operation. The steps that must be performed to integrate the Authentication Cloud into your application are in bold.

The following conditions must be met to enable SMS authentication:

  • You have an active SMS subscription enabled and configured on your account. Contact Nevis support for details.
  • The user account is successfully registered for SMS.

Send an HTTP request to the approval endpoint​

For detailed information on the HTTP request parameters and response fields, see the Approval endpoint page of the API reference documentation.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/approval call with your instance ID, and configure the HTTP request as follows:

  1. Send your access key or intent token in the Authorization Bearer token header. For more information on the intent token, see Intent endpoint.
  2. Set the channel parameter to sms.
  3. Add the username or the userId parameter.
  4. Optionally, add a message using the message parameter to send in the SMS. The message must contain a {{CODE}} placeholder for the code that is generated by Authentication Cloud after the approval request. If you omit the message parameter, a default message containing the '{{CODE}}' will be used in the SMS.

HTTP request example​

cURL code sample for authenticating a transaction with SMS
curl -v -X POST https://$instance.mauth.nevis.cloud/api/v1/approval \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $access_key" \
  -d "{ \"username\":\"$username\",
        \"channel\":\"sms\",
        \"message\":\"SMS Transaction Approval Test, code: {{CODE}}\" }"

HTTP response example​

{
  "statusToken": "eyJhbGciOiJIUzUxMiJ9.eyJhd...hInHRfSw",
  "transactionId": "d9db4760-...-5cbe533389e3",
  "userId": "7a342fb4-...-bb837ed32d9d"
}

Prompt user to enter code​

After receiving an approval HTTP request, Authentication Cloud sends its own HTTP request to the SMS service provider, containing the phone number of the user, and if added, a message with a code. The service provider then sends an SMS with the message content to the provided phone number.

Ensure that you create a prompt in your frontend for the user to enter the received code. After the user provides the code, you must verify it with an HTTP request to the verification endpoint.

Send an HTTP request to the verification endpoint​

For detailed information on the HTTP request parameters and response fields, see the Verification endpoint page of the API reference documentation.

The userId and the statusToken are returned as JSON object members by the previous API call to the approval endpoint. The code is the mTAN delivered as an SMS.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/users/{userId}/verification call with your instance ID and with the user ID of the given user, and configure the HTTP request as follows:

  1. Send your access key in the Authorization Bearer token header.
  2. Set the following parameters:
    • code
    • statusToken

After the verification request is sent, Authentication Cloud checks whether the user is rate limited. If the user is rate limited, the the authentication operation fails.

HTTP request example​

cURL code sample to verify the code
curl -v -X POST https://$instance.mauth.nevis.cloud/api/v1/users/$userId/verification \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $access_key" \
  -d "{ \"code\":\"$code\",
        \"statusToken\":\"$statusToken\" }"

HTTP response example​

HTTP/1.1 200 OK

The response is either an HTTP/1.1 200 if the verification is successful, or an HTTP/1.1 4xx otherwise.