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:

Click 'Generate new application' to create your application.

Generate a JWT

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:

    curl -X POST 'https://api.nexmo.com/v2/verify' \
    -H 'Authorization: Bearer $JWT' \
    -H 'Content-Type: application/json' \
    -d '{"brand": "Your Brand",
        "workflow": [
        {"to": "447701000002", "channel": "silent_auth","sandbox":true }]
    }' 

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

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

{
  "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
  "check_url": "https://api.nexmo.com/v2/verify/31eaf23d-b2db-4c42-9d1d-e847e75ab330/silent-auth/redirect"
}

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:

{
    "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
    "triggered_at": "2020-01-01T14:00:00.000Z",
    "type": "event",
    "channel": "silent_auth",
    "status": "action_pending",
    "action": {
        "type":"check"
        "check_url": "https://eu.api.silent.auth/phone_check/v0.1/checks/c11236f4-00bf-4b89-84ba-88b25df97315/redirect"
    }
}

You'll need to send a

HTTP/1.1 302 Found
Location: https://eu.api.silentauth.com/phone_check/v0.2/checks/31eaf23d-b2db-4c42-9d1d-e847e75ab330/redirect

HTTP/1.1 308 Temporary Redirect
Location: https://sandbox.redirect.m-auth.com/callback/sandbox?id=31eaf23d-b2db-4c42-9d1d-e847e75ab330

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

{
  "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
  "code": "si9sfG"
}

Send your code to the check code endpoint

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

curl --X POST \
  --url https://api.nexmo.com/v2/verify/$REQUEST_ID \
  -H "Authorization: Bearer "$JWT\
  -H 'Content-Type: application/json' \
  -d $'{
    "code": "si9sfG"
}'

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
  "status": "completed"
}

Or if the verification has failed:

HTTP/1.1 409 CONFLICT
Content-Type: application/json

{
  "title": "Network error",
  "detail": "The Silent Auth request could not be completed due to formatting or the carrier is not supported."
}