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.

Using the SDKs also helps you minimize UX impact in edge cases:

Connectivity checks (for example sdk_no_data_connectivity) so you can trigger faster, seamless failover.
Timeout management between redirects to reduce waiting under slow mobile data conditions.
iOS 26 support in applicable markets (for example Spain).

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

Use Regional Endpoints to Reduce Latency

To improve latency for Silent Authentication, we recommend using the Vonage regional endpoint that matches your end user's location:

North America: api-us.vonage.com
Europe: api-eu.vonage.com
Asia: api-ap.vonage.com

By using regional endpoints, you ensure that requests are routed along the shortest possible path, which helps minimize delays caused by redirects.

Note: Using a non-regional (global) endpoint will route US traffic through the US. However, all other traffic, including that from Asia Pacific (AP), will be routed through Europe, which may result in increased latency.

Front-end

Silent Authentication within Verify presents an easy and straightforward way to authenticate a user, providing an enhanced user experience compared to 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. In this case, the end-user could be presented with pre-filled text fields and the only action needed is to select "Verify".

During the Silent Authentication experience, ensure that the user is familiar with the process and aware that the authentication process is running in the background.

In-progress State

To set expectations while authentication runs in the background, it is recommended to:

Present a spinning wheel or similar feedback mechanism so the end-user knows that the mobile application is working on the authentication task.
Alternatively, show a dedicated screen with the same loading indicator and additional text.

Success Path

If Silent Authentication completes successfully, the user should be taken to a clear success state without needing to enter a code.

Fallback Path

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.

To summarize, the figure below illustrates both user journeys: the success path (Silent Authentication completes in the background) and the fallback path (the user is prompted to enter a failover code).

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.

Avoid Starting Silent Auth Without Mobile Data

Before initiating a Silent Authentication request, use the Client Libraries to explicitly run a cellular connectivity pre-check. If the SDK detects that mobile data is unavailable (for example, the device is on Wi-Fi only or has no signal), it returns false (iOS) or CellularStatus.Unavailable (Android). Your app should check this result and proceed to the fallback channel. This avoids unnecessary request attempts and reduces overall verification time. For implementation details, see the iOS Client Library README or Android Client Library README.

If the pre-check fails, the Silent Authentication channel should be skipped. Your backend can still call POST /v2/verify, but should do so without the Silent Authentication channel, using only your chosen fallback channels (for example SMS, RCS, or voice). In this case, no check_url is returned and next_workflow is not needed, as the fallback channel is initiated directly.

Note: If connectivity issues occur after the Verify request has been created (for example, a network interruption while loading check_url), the SDK can throw exceptions such as sdk_no_data_connectivity. In this case, use the returned request_id and call next_workflow immediately via your backend. See Timeout Behaviour for details.

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 two failure scenarios: (1) the SDK pre-check detects that mobile data is unavailable — Silent Auth is skipped (so no check_url is returned), and (2) a Verify request is created successfully but the mobile app fails to complete the redirect flow while loading check_url (for example due to network issues):

Recommended Flow

Before initiating Silent Authentication, explicitly call the SDK pre-check method to verify cellular connectivity. For implementation details, see the iOS Client Library README or Android Client Library README.
If the pre-check returns false (iOS) or CellularStatus.Unavailable (Android), skip the Silent Authentication channel. Your backend can still call POST /v2/verify, but should do so without the Silent Authentication channel — using only your chosen fallback channels (for example SMS, RCS, or voice). In this case, no check_url is returned and next_workflow is not needed, as the fallback channel is initiated directly.
If the pre-check passes, start Silent Authentication and request check_url via your backend (POST /v2/verify).
Wait for the Silent Authentication to complete in the background. On success, proceed to the authenticated state.
If an exception occurs after a Verify request is created (for example while loading check_url), catch it and call your backend to trigger next_workflow (requires request_id).
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.

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

`next_workflow` Retry Behaviour

When next_workflow is called while Silent Authentication is still completing its setup, Verify queues the event and retries it internally for a short window.

If Silent Authentication takes unusually long to start and next_workflow is called very early in the flow, the retry window may expire. In that case, the API returns an HTTP 409 Conflict error, instructing you to retry:

{
  "type": "https://developer.vonage.com/en/api-errors/verify-v2#conflict",
  "title": "Conflict",
  "detail": "The operation cannot be performed at this time. Please try again later.",
  "instance": "my-trace-id-trigger-next-replication-delay"
}

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
6	`next_workflow` received too early during Silent Authentication setup	HTTP 409	`{ "title": "Conflict", "detail": "The operation cannot be performed at this time. Please try again later."}`	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:

Use virtual numbers.
Allow listing numbers for supported networks through the Network Registry.

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