Silent Authentication - Best Practices

Bypass WiFi and Force Mobile Data Connection with the SDKs

Silent Authentication requires an active mobile data connection. If the request is made over Wi-Fi, it will result in an error. To ensure a successful request even when the user is on WiFi, Vonage provides native iOS and Android SDKs that enforce a mobile data connection.

Additionally, the Vonage SDKs handle HTTP redirects (up to 10) and manage timeouts (5 seconds, resetting after each redirect).

Front-end

Silent Authentication within Verify presents an easy and straightforward way to authenticate a user providing an enhanced user experience when comparing with other channels.

For new account creation use cases, the mobile application will not know the phone number of the end-user, so the phone number must be collected via an input field on the welcome screen.

Alternatively, an end-user that already has an account and is attempting a passwordless login will already have their phone number stored, at which point the end-user could be presented with pre-filled text fields and the only action needed is to “log in”.

Silent Authentication Passwordless experience

During the Silent Authentication experience it is important to ensure that the user is familiar with the process and aware that the authentication process is running in the background. It is also important to ensure that in the event of a failure, both front-end and backend failover implementations are not cumbersome for the end user. It is recommended to present the user with a spinning wheel or similar feedback mechanism so the end-user knows that the mobile application is working on the authentication task. Alternatively, a new screen with the same loading indicator and additional text would achieve the same result.

Silent Authentication Spinning Wheel

In the event of a failure during the Silent Authentication flow, the application front-end needs to be adjusted so that the user can insert the pin code to complete the 2FA process. This code will be delivered via the failover channels.

Silent Authentication Failover

Handling Errors and Timeouts in Silent Authentication

Due to its nature, Silent Authentication may be affected by external conditions such as a lack of mobile data connectivity or temporary network interruptions. To ensure a smooth user experience, your mobile app should rely on the Client Library's built-in exception handling rather than implementing its own network checks and timeout management.

When the SDK encounters a problem, it will throw specific exceptions that indicate what went wrong. For example, sdk_no_data_connectivity, thrown when no mobile data connection is available.

Timeout Behaviour

Your app should catch these exceptions and notify your backend to call the next_workflow endpoint immediately. This ensures that the verification flow continues gracefully even when the Silent Authentication workflow fails or cannot proceed.

If the mobile app does not take any action to move to the next workflow, the system will automatically timeout after 60 seconds and proceed to the next workflow.

The sequence diagram below illustrates a situation where redirects are not properly received by the mobile app, possibly due to network issues during the request of check_url:

VonageApp BackendMobile AppVonageApp BackendMobile AppMobile app catches the exception thrown by client libraryVerify phone numberPOST v2/verifyWebhook 202 OK (check_url, request_id)Response (check_url)GET check_url fails due to network issuesNotify to move to the next Workflow (request_id, error)POST v2/verify/:request_id/next_workflow
  1. Start the Silent Authentication request using the SDK.
  2. If the SDK throws an exception (e.g., sdk_no_data_connectivity), catch it and immediately call your backend’s next_workflow endpoint.
  3. If no response or callback is received within your app’s internal timeout (e.g., before the 60-second default), call next_workflow as well.
  4. Otherwise, wait for the normal authentication callback.

This approach minimizes waiting time, improves user experience, and ensures your backend always advances to the correct step in the workflow.

Failover Scenarios

In this section we list all scenarios that can occur during a Silent Authentication request and advise failover implementations to ensure the finest end-user experience.

Some scenarios trigger an immediate failover to the next channel, however there are cases where the failover is only triggered after the default Silent Authentication default timeout of 60 seconds. Please refer to the table below, which summarizes the different failure scenarios:

Scenario Failure Reason Failure Code Failure Response Immediate Failover?
1 Silent Auth Error HTTP 409 { "title": "Silent Auth error", "detail": "The Silent Auth request could not be completed due to formatting or the carrier is not supported."} Yes
2 MSISDN Error HTTP 409 { "title": "MSISDN Error", "detail": "Device MSISDN does not match."} Yes
3 Network not supported HTTP 412 { "title": "Network not supported", "detail": "Device number does not resolve to a supported Mobile Network Operator."} Yes
4 IP Error HTTP 412 { "title": "IP Error", "detail": "IP Address does not resolve to a cellular device."} Yes
5 iOS/Android SDK Errors -- sdk_no_data_connectivity, sdk_connection_error, sdk_redirect_error, sdk_error No

Silent Authentication Billing

When a Silent Authentication request is initiated, it generates one entry for the Verify platform fee and one or two additional entries representing the Silent Authentication usage. The entry marked as INITIATED is never billed. In total, a single Silent Authentication request may have up to three associated records.

Testing

To test Verify Silent Authentication, you can do the following:

If a customer needs to send live traffic, they must register with the mobile operator via the Network Registry.