Using the Silent Authentication Sandbox

Silent Authentication uses a mobile phone's Subscriber Identity Module (SIM) to prove a user's identity, without any user input. In order to test a successful verification, code needs to be run from an application running on a phone over a mobile network - this can be difficult to do, so this guide will explain how to configure and use a sandbox for use with Silent Authentication.

There are five steps to get the sandbox up and running:

  1. Create an application
  2. Generate a JWT
  3. Send the silent authentication request
  4. Send a GET request to the check_url in your callback
  5. Send your code to the check code endpoint

Create an application

First, you need to create an application in the Vonage developer dashboard. Enter a name for your application and click 'Generate public and private key' - your private key will be used to generate a JWT in the next step. Enable the Verify API and set the Status URL to your webhook to receive callbacks for your requests:

Create an application using the Vonage developer dashboard.

Click 'Generate new application' to create your application.

Generate a JWT

To use Silent Authentication, you must use JWT Authentication in your requests otherwise you will not receive the necessary webhooks to implement it.

Next, you will need to generate a JWT to authenticate your requests - instructions on how to do so can be found here. You will need your Application ID and Private Key from the previous step.

Send the silent authentication request

Now you will send a silent authentication request. In the following example, replace $JWT with your JWT:

You can change the outcome of the silent authentication check using the value of the to field:

to field Outcome
00, 50, 99 failed - unable to complete the check.
Odd number, e.g. 447700900001 user_rejected - successful check, but the user was not authenticated.
Even number, e.g. 447700900002 completed - successful check, and the user was authenticated.

Once you've sent the request, you'll get a response containing your request_id and a check_url:

Send a GET request to the check_url in your callback

The next thing you will receive is an event to your callback that says status: action_pending - this means that the API is waiting for the result of the silent authentication check. As the request is not going to the carrier, you will need to complete this yourself. In the event, you will find a check_url - you'll need to send a

GET
request to the URL. This will result in several HTTP30x responses that you'll need to follow:

Note: If the check_url is not opened within 25 seconds, the returned status will be expired.

Once you've followed the redirects, you'll receive a code:

Send your code to the check code endpoint

To complete the check, send the code to the check-code endpoint:

You will receive a final response containing the result of the check. If successful:

Or if the verification has failed: