Getting Started with the Number Verification API

Imagine you want to improve the security of your platform or service to protect your users and prevent fraud. To address this, you decide to implement a two-factor authentication (2FA) process to provide an additional layer of protection for your users. Instead of relying on traditional SMS-based 2FA, which can be vulnerable to SIM-swapping and other attacks, let’s choose a different method: authentication based on your users' phone numbers.

The Number Verification API verifies an end-user using the phone number linked to the SIM card in the device connected to the mobile data network. It improves the user experience by reducing the need for repeated logins and One-Time Passwords (OTP), especially in scenarios where the user is already logged in to a service or system.

Prerequisites

Before you begin, you'll need the following:

• A Vonage account: Sign up here if you don't already have one.
• Node.js and npm: You'll need these tools to create the sample application, so ensure they're installed on your machine.

Set up the environment

When working with the Network APIs, there are two different environments:

• Production. This environment returns live data from the supported Operators in some countries. Access to the production environment requires approval from the mobile operators. To learn how to request access, follow this guide.
• Playground. The Playground is a safe and controlled testing environment where API calls return live data only for a small group of allowlisted phone numbers. Unlike production, it does not require approval from Operators. Additionally, the Playground provides access to the Virtual Operator, a simulated operator that generates fake but deterministic responses.

In this guide, we will use the Playground Environment with the Virtual Operator for two key reasons:

• It allows immediate use of the APIs without needing approval from the Operators.
• It enables testing the APIs from anywhere in the world.

Create a New Application

To get started, we need to create a new application. This application will contain the credentials required for making API calls. Follow these steps:

• Go to the Dashboard and select "Applications" from the left side menu.
• Click the "Create a new application" button.
• Enter a name for your application in the "Name" field.
• Click "Generate public and private key" to generate a key pair. A private key file will be automatically downloaded. Save this file securely, as it is requried for generating JWTs.
• Scroll to the capabilities section and enable the "Network Registry" capability. Make sure the "Playground" environment is selected.
• In the Number Verification Redirect field, enter the URL where your backend will be running. The URL should contain an endpoint for the callback. For example https://yourhost.com/callback
• Click the "Generate new application" button to finish the creation process.

After the application is created, copy the Application ID displayed on the dashboard. You will need this Application ID along with the private key file to generate JWTs for authenticating API requests.

Architecture

In this guide, we’ll walk through building an application that shows how to use the Number Verification API. Specifically, we’ll create:

• A backend application: This will implement the API calls to verify phone numbers.
• A CLI client: Acting as a simulated service, it will authenticate end-users via their mobile phone numbers.

While the Number Verification API is typically integrated with mobile (or web) applications to authenticate end-users, this guide simplifies the process by using a command-line interface (CLI) client for demonstration purposes.

The steps needed to integrate Number Verification API are described in the following diagram:

For more information about this flow, refer to the client authentication guide .

Backend implementation

The backend will handle incoming requests from the client and make the necessary API calls to complete the authentication flow.

Our backend will expose the following endpoints:

• login. This endpoint will handle
  POST
  requests to initiate the user authentication process. It will call the Network Enablement API to bootstrap the authentication flow.
• callback. This endpoint will be triggered as a callback by mobile Operator. It will finalize the authentication process by requesting an access token needed to call the Number Verification API.

Step 1: Initialize Authentication with the Network Enablement API

The /login endpoint initializes the authentication flow using the Network Enablement API. This API improves the existing authentication flow, particularly those requiring client authentication, such as the Number Verification API, by increasing performance, privacy, and security.

Request Body

The Network Enablement API request body should look like this:

Where:

• phone_number corresponds with the phone number provided by the client app.
• scopes contains a list of scopes. In our example, the list includes the scope for Number Verification API.
• state. A unique, randomly generated string (20 characters) to ensure request validity.

Headers

Include the following headers in the request:

API Request

Use the following code snippet to call the Network Enablement API:

API Response

The Network Enablement API response contains information about the authentication request. Here's an example response:

Return the auth_url to the client for the next step.

Step 2: Authorization Request from the Client

The client will use the auth_url provided by the backend to complete the authorization process. For details, see the Test the Backend section.

Step 3: Callback

If everything goes well, the operator redirects to the backend's callback endpoint specified by the redirect_uri configuration from the Dashboard. The callback contains two query parameters:

• code (string): Corresponds to the authorization code that can be exchanged for an access token.
• state (string): Contains the exact value of the state parameter supplied in the previous request.

For example: https://mycompany.com/callback?code=EapDCg..B8W1Q&state=foobar.

If there is an error, the callback will contain the following query parameters:

• error: Contains the reason why the authorization failed (e.g. server_error)
• error_description: Contains a human-readable description of the error.

Step 4: Exchange Authorization Code for an Access Token

Once the backend receives a callback from the Vonage auth server with a valid authorization code, you must exchange it for an access token. To do so, send a

request to the /token endpoint.

Request Body

• grant_type. Must be set to authorization_code.
• code. Corresponds with the authorization code received in the callback from the previous step.
• redirect_uri. This parameter is used for validation only as this step has no actual redirection. The value of this parameter must match the redirect_uri parameter from the dashboard configuration.

Headers

The request must contain the following HTTP headers:

• Authorization: The value must be set to Bearer + JWT token. To generate the JWT you can use our online generator, or alternatively use the Vonage CLI.
• Content-Type: This header must be set to application/x-www-form-urlencoded.

API Request

The following JavaScript example implements the exchange of the authorization code to request a new access token:

API Respones

On success, the response will contain a 200 OK status along with the following body represented in this example:

Where:

• access_token (string) contains the token you'll use during the Number Verification API call.
• token_type (string) will always contain the Bearer string.
• expires_in (integer) specifies the expiration time of the token in minutes.

Step 5: Call the Number Verification API

The last step is to call the Number Verification API using the access token you obtained in the previous step.

Body Request

The API has one single endpoint, /verify, that supports only a

operation with the following format.

The request body contain one element, phoneNumber, corresponding to the phone number (with the international prefix) you want to verify.

Headers

The request must contain the following headers:

• Content-Type must be set to application/json
• Authorization must be set as Bearer access_token, where access_token is the value of the token obtained in the previous step.

API Request

The following JavaScript code snippet implements the

request to the /verify endpoint:

API Response

The response of the API will contain the verification of the phone number using a boolean value:

Once you receive the response from the Number Verification API, you can inform the user whether the authentication worked successfully. You could then continue with the application's normal login flow, or even implement more security measures on the client side.

Test the Backend

Although, the Number Verificaion API is usually used by mobile applications, we are going to use a Python script to act as client and test the backend implementation.

The client has two methods: login and auth.

login

Initiates the authentication process by sending a

request to the /login endpoint of the backend. The body request contains the phone number we want to verify. The method returns the authorization URL returned by the Network Enablement API call on backend side.

auth

This method corresponds to Step 2 in the Architecture diagram. Completes the authentication process by using the provided authorization URL to verify the phone number.

CLI

We can test the verification of a given phone number using the command-line. The following example verifies the phone number +99012345678 using the Virtual Operator:

The process flow is as follow:

• Calls the login(phone) function to initiate authentication and retrieve the auth_url.
• Passes the auth_url to the auth(url) function to verify the phone number.
• Prints success or failure messages based on the verification result.

Source Code

You can find the complete source code for this tutorial in the GitHub repository.

Further Reading

• Read more about the Number Verification API in the API Reference and on our developer blog.
• If you're ready to request approval from the operators, refer to the Network Registry Guide for detailed instructions.
• If you have any questions, you can reach out to us on the Vonage Community Slack.