Skip to main content

Register a phone number

Registering a phone number enables your users to implement second-factor authentication using only a phone number and any mobile device. It means that mTAN via SMS is used as the second factor in addition to their existing authentication process, such as a username and password.

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

Send an HTTP request to the registration endpoint​

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

To register a phone number, you must have an active SMS subscription enabled and configured on your account. Contact the Nevis support for details.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/users/enroll 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. Set the username or userId parameter. You can only use the userId parameter if the user already exists. The userId can be found in the registration HTTP response.

    Use unique static information for the username parameter. To link a user to your internal systems, you might use, for example, an internal customer ID or employee ID, and provide that as a username in the user registration request. It is important to use information that does not change over the life cycle of a user.

    Do not use a username with any Personally Identifiable Information (PII). For example, an email address is not recommended because it is not only PII data, but it also might change over the lifecycle of a user.

    Preventing User Impersonation

    To prevent impersonation, ensure you only link users to your backend records after strongly authenticating them first.

  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 registration request. If you omit the message parameter, a default message containing the '{{CODE}}' will be used in the SMS.
  5. Set the phone parameter in the international phone number format.

HTTP request example​

cURL code sample for requesting an SMS code for registration
curl -X POST https://$instance.mauth.nevis.cloud/api/v1/users/enroll \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $access_key" \
-d "{ \"username\":\"$username\",
        \"channel\":\"sms\",
        \"message\":\"SMS Registration Test, code: {{CODE}}\",
        \"phone\":\"$phone\"
    }"

HTTP response example​

{
    "authenticators": [],
    "createdAt": "2021-06-28T11:53:33.312492Z",
    "enrollment": {
        "statusToken": "eyJhbGciiJ9.ey..._ZQ6D8tw",
        "transactionId": "4bb078e1-...-20ee97eaca2d"},
    "phones": [],
    "recoveryCodes": null,
    "status": "new",
    "updatedAt": "2021-06-28T11:53:33.312493Z",
    "userId": "02c14dba-bdb2-...-9474c59a40d1",
    "username": "TestUser"
}

Prompt user to enter code​

Once the user is created, Authentication Cloud sends an 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 registration 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 registration operation fails.

HTTP request example​

cURL code sample to verify the registration
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​

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

HTTP/1.1 200 OK