Asynchronous Implementation
An asynchronous implementation is very similar to the synchronous method; instead of using the device client to make a series of calls, every part of the workflow is included in webhook callbacks sent to a URL you define.
This guide explains how to implement silent authentication using the asynchronous approach, where your backend sets up a callback to receive the authentication result.
To use Asynchronous Silent Authentication, you must use JWT Authentication in your requests otherwise you will not receive the necessary webhooks to implement it.
Create an Application
To begin, go to the developer dashboard to create your application:
- Ensure that Verify is enabled under 'Capabilities'.
- Configure the Status URL to receive callback events.
- Generate a JWT using the Application ID and private key of the application.
Request Verification Code
To start the silent authentication process, make a request to /verify. In the following example, the workflow specifies that Verify will first attempt to use Silent Authentication. If for any reason the request fails, it will then fallback to email OTP.
To run the example, replace the following variables in the sample code with your own values:
| Variable | Description |
|---|---|
JWT | Authenticates the API request using JWT. |
VERIFY_BRAND_NAME | The name of your company or service, shown to the user in the verification message. |
VONAGE_APPLICATION_PRIVATE_KEY_PATH | Path to the private key of your application. |
VONAGE_APPLICATION_ID | Application ID of your application. |
VERIFY_NUMBER | The phone number to send the OTP to, in E.164 format (e.g., +44111223344). |
VERIFY_TO_EMAIL | The email to send the OTP to. |
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named send-request-with-fallback.js and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named SendVerificationRequestWithFallback and add the following code to the main method:
Write the code
Add the following to the main method of the SendVerificationRequestWithFallback file:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.verify with the package containing SendVerificationRequestWithFallback:
Prerequisites
Add the following to build.gradle:
Create a file named SendRequestWithFallback and add the following code to the main method:
Write the code
Add the following to the main method of the SendRequestWithFallback file:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.verify2 with the package containing SendRequestWithFallback:
Prerequisites
Create a file named StartVerificationRequestWithFallback.cs and add the following code:
Add the following to StartVerificationRequestWithFallback.cs:
Prerequisites
Create a file named request.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named request.rb and add the following code:
Run your code
Save this file to your machine and run it:
You will receive callbacks to the URL specified in your application settings informing you of the progress of the request. It is possible that the request will fail at this point, for example if there is an error in the network. Again, if you have another channel specified in your request, Verify will fallback to it. If the request is successful the first response will contain a check_url:
Until the request expires or is cancelled, check_url will be used to perform a Silent Authentication check. Upon receiving this callback, you need to make a
check_url from the mobile device you are trying to authenticate. In order for the Mobile Network Operator to properly verify the user, the
Once you've made the
302 redirects depending on the territory and carrier the target device is using: Following the redirects will result in either a HTTP 200 or HTTP 409 response depending on whether the request is valid. If there is a problem with the network, you'll see a response like this:
A full list of potential error codes can be found in the API Specification.
If the request is valid, you will receive an HTTP 200 response containing your request_id and a code:
Note: To ensure a secure authentication check and mitigate against a potential man in the middle attack, store the original request_id and compare it with the request_id returned in the response. If the IDs don't match, the silent authentication check should be aborted. See our sample application for an example implementation of how to mitigate against the attack.
Check the Supplied Verification Code
Once the end-user receives the code, you must send a
/v2/verify/{request_id} endpoint, replacing {request_id} with the ID you received in the previous call. To run the example, replace the following variables in the sample code with your own values:
| Variable | Description |
|---|---|
JWT | Authenticates the API request using JWT. |
VERIFY_REQUEST_ID | The request_id received in the previous step. |
VONAGE_APPLICATION_PRIVATE_KEY_PATH | Private key of your application. |
VONAGE_APPLICATION_ID | Application ID of your application. |
VERIFY_CODE | The verification code received by the end-user |
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named check-verification-code.js and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named CheckVerificationCode and add the following code to the main method:
Write the code
Add the following to the main method of the CheckVerificationCode file:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.verify with the package containing CheckVerificationCode:
Prerequisites
Add the following to build.gradle:
Create a file named CheckVerificationCode and add the following code to the main method:
Write the code
Add the following to the main method of the CheckVerificationCode file:
Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.verify2 with the package containing CheckVerificationCode:
Prerequisites
Create a file named VerifyCodeRequest.cs and add the following code:
Add the following to VerifyCodeRequest.cs:
Prerequisites
Create a file named send_code.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named check.rb and add the following code:
Run your code
Save this file to your machine and run it:
Note: a code for a silent authentication workflow can only be checked once.
If the code is valid, you will receive a callback with the status completed:
Or, if there is an error, you will see 'Invalid Code':
You will then receive a final callback with the result of the check. If successful, you will see a callback with "status": "completed":
If unsuccessful, for example if the user has been rejected, this will be indicated in the status field:
At this point, your silent authentication verification is complete.