Client Authentication

Prerequisites

This guide assumes you have completed the following requirements:

• The Network Features 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 Feature auth endpoints is available here.

Authentication Flow

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

Step 1: Send Request to the Backend

The process starts when the mobile application needs to verify 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 must integrate 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.

To call the Network Enablement API, send a

Headers

Body Parameters

Request Example

curl -X POST https://api-eu.vonage.com/v0.1/network-enablement \
  --header "Authorization: Bearer $JWT" \
  --header "Content-Type: application/json" \
  --data $'{
    "phone_number": "'$PHONE_NUMBER'",
    "scopes": ["dpv:FraudPreventionAndDetection#number-verification-verify-read"],
    "state" : "'$STATE'"
}'

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
    }
  }
}

Finally, the backend returns the auth_url to the mobile application.

Step 3: Authorization Request

The mobile application sends a

Step 4: Exchange Auth Code for an Access Token

The previous redirect will result in a callback from the Vonage backend to our backend at the redirect_uri defined in the application dashboard. This callback will include query parameters that need to be parsed.

Query Parameters

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

Example

https://example.com/callback?code=12a56g213ad69asdjfc322&state=1a2bc4ae

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

Headers

Body Parameters

Request Example

curl -X POST https://api-eu.vonage.com/oauth2/token \
  --header "Authorization: Bearer $JWT" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "code=$AUTH_CODE" \
  --data-urlencode "redirect_uri=$REDIRECT_URI" \
  --data-urlencode "grant_type=authorization_code"

Response Example

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

{
  "access_token": "$ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 5: 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.

Request Example

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

curl -X POST https://api-eu.vonage.com/camara/number-verification/v031/verify \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "phoneNumber": "'$PHONE_NUMBER'" }'

Response Example

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

{
    "devicePhoneNumberVerified": true
}

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.