Client Authentication

Prerequisites

This guide assumes you have completed the following requirements:

The Network APIs capability is enabled in your Vonage application. Follow this guide to read detailed information on how to do it.
You have a valid JWT. You can use our online generator to create a JWT using your private key and the ID of your Vonage application, both found in the customer dashboard, or follow the instructions here to use another method.

Auth API Reference

The OpenAPI specification for the Network API auth endpoints is available here.

Authentication Flow

Making an API call using the client authentication flow comprises of the following steps:

Step 1: Send authentication request to the backend

The process starts when the mobile application needs to authenticate an end user using their phone number. The mobile application sends a request to the backend application to initiate the authentication.

Step 2: Network Enablement API call

The backend application integrates with the Network Enablement API to pre-check that the phone number provided is on a mobile network that supports the Number Verification API and that you are using the API for a purpose that the associated mobile network allows.

The Network Enablement API must be integrated on backend side.

Body Parameters

Parameter	Required	Type	Description
`phone_number`	Yes	string	The phone number of the user in E.164 format, including the country code.
`scope`	Yes	Array of string	A list of permission scopes that define the specific access or operations being requested for the API call. See the scopes guide.
`state`	Yes	string	A generated value used to maintain state between the request and callback. Must be unique for each request.

Headers

Header	Description
`Authorization`	Must be set to `Bearer` along with the `JWT` token generated in the previous step. The `JWT` must correlate to the App that is approved for the Network APIs usage.
`Content-Type`	Must be set to `application/json`.

Request Example

Response Example

{
  "scopes": {
    "dpv:FraudPreventionAndDetection#number-verification-verify-read": {
      "auth_url": "https://api-eu.vonage.com/oauth2/auth?client_id=sandbox_test&scope=dpv%3AFraudPreventionAndDetection%23number-verification-verify-read&state=v2_840e17a8-79f2-1a277bff&redirect_uri=https%3A%2F%2Fui.idp.vonage.com%2Fcamara%2Foauth%2Fcallback&response_type=code",
      "requires_carrier_network": false
    }
  }
}

Step 3: Response to mobile application

The Network Enablement API returns the URL (auth_url), which is then sent to the mobile application.

Step 4: Authorization request

The mobile application calls to the auth_url received from the backend.

Step 5: Callback with authorization code

Once the client authorization request is made, the mobile operator sends a callback to the backend application with a 200 OK status to the redirect_uri defined in the application dashboard. This request will include query parameters that need to be parsed.

Query Parameters

Parameter	Type	Description
`code`	string	Contains an authentication code that is used to exchange for an `access_token` in the next step.
`state`	string	It corresponds with the state sent in the Network Enablement API request.

In the event of an error, the callback will include the following parameters:

Parameter	Type	Description
`error`	string	The reason authorization failed, for example: access_denied.
`error_description`	string	Human readable error description.

Example

Step 6: Exchange Auth Code for an access token

To exchange the authorization code for an access token, send a

POST

request to https://api-eu.vonage.com/oauth2/token

Body Parameters

Parameter	Required	Type	Description
`grant_type`	Yes	string	Must be set to `authorization_code`
`code`	Yes	string	The code received in the callback.
`redirect_uri`	Yes	string	The Redirect URI set in the application settings in the dashboard

Headers

Header	Description
`Authorization`	Must be set to `Bearer` along with the `JWT` token generated in the previous step. The `JWT` must correlate to the App that is approved for the Network APIs usage.
`Content-Type`	Must be set to `application/x-www-form-urlencoded`.

Request Example

Response Example

On success, the response will have a 200 OK status and the following JSON data in the response body:

Parameter	Type	Description
`access_token`	string	The access token that will be used during the API calls.
`token_type`	string	It is always set to `Bearer`.
`expires_in`	int	The time period (in seconds) for which the access token is valid.

Steps 7: Number Verification API call

Your backend application uses the access token to call the Number Verification API, providing the end-user’s phone number to verify.

Header	Description
`Authorization`	Must be set to `Bearer` along with the `access token` generated in the previous step.

Request Example

The following example shows how to make an API call to Number Verification API using the access token:

The Number Verification API informs your backend application whether the end user is on a device that matches the phone number they provided. You can then allow your frontend application to access secure resources on your backend, confident that the end users are who they claim to be.