Vonage Protection Suite for Okta

Layer	Product	When It Runs	What It Does	Cost
Layer 1 (Pre-OTP)	Identity Insights	Before OTP is sent	Screens number against carrier databases: validity, carrier. Blocks fraud before delivery.	Per-request (optional)
Layer 2 (During OTP)	Fraud Defender	During OTP delivery	SMS pumping protection, geographic permissions, velocity controls, rate limiting.	Advanced: Free with Verify. Premium: Paid.

User Roles

This guide is organized by the primary user role involved in deploying and operating the connector:

For Admin User — Installation & Configuration Guide

This section walks the administrator through the complete setup process, from deploying the connector on Vonage Cloud Runtime to configuring Okta and verifying the integration. Follow the steps in order.

Step 1: Deploy the Connector on Vonage Cloud Runtime

Deploy a new instance of the Vonage Protection Suite for Okta from the VCR Marketplace.

• Select Your API Key and Deploy a New Instance

  In the Vonage dashboard, select your API key, then click "Deploy a new instance" for the "Vonage Protection Suite for Okta" application.
  
  
   

• Configuration Type

  Version 1.0 offers one deployment configuration: Standard. Select "Standard" and click "Continue".
  
  
   

• Fill in the Configuration Details
  Region and instance name: Choose the region for your instance and provide a unique, concise name.
  
  
  
  - Vonage Number (optional): If configured, this number is used as the sender ID for SMS. Must be in E.164 digits-only format (international number without the "+" sign). If not configured, the Brand Name below is used instead. For voice calls, this value is ignored — the caller number is randomly selected by Vonage Verify.
  - Brand Name (mandatory): The OTP message body will use this brand name for SMS. For voice calls, this value is ignored.
  - Voice Call Fallback (mandatory): When enabled, the connector automatically retries via voice call if SMS delivery fails.
  
  

Select "Continue" to deploy the instance.

Step 2: Configure the Connector (Admin Application)

After deployment, launch the connector’s Admin Application to configure security policies and generate authentication tokens.

2a. Launch the Admin Application

Authenticate using your Vonage credentials.

2b. Dashboard Tab

The Dashboard tab provides real-time visibility into OTP delivery and authentication activity.

Counters

The Counters section displays the following metrics:

• Total SMS: Total SMS delivery attempts (success + failure).
• SMS Success: SMS deliveries completed successfully.
• SMS Blocked: SMS deliveries blocked by Identity Insights or Fraud Defender.
• Total Voice: Total voice delivery attempts (success + failure).
• Voice Success: Voice deliveries completed successfully.
• Voice Blocked: Voice deliveries blocked.

Recent OTP Activity

The last 10 OTP delivery events across all tokens, showing Timestamp, Destination (masked), Channel (SMS/Voice), Status (SUCCESS/FAILED/FLAGGED), Description, Latency, and Token identifier.

• Timestamp: When the delivery was attempted.
• Destination: The masked phone number.
• Channel: SMS or VOICE.
• Status: SUCCESS, FAILED, or FLAGGED (amber, for flag-and-deliver).
• Description: Click the eye icon to view the full failure or flag reason.
• Latency: Time taken to complete the delivery in milliseconds.
• Token: The truncated token identifier.

Recent Auth Events

The last 10 authentication events received from Okta, showing Timestamp, Token, Event type, Factor, Outcome, User, and Request ID.

• Timestamp: When the event was published.
• Token: The truncated token identifier.
• Event: The Okta event type (e.g. user.authentication.auth_via_mfa).
• Factor: The authentication factor (e.g. SMS_FACTOR, CONVERSION).
• Outcome: SUCCESS, FAILURE, or UNKNOWN.
• User: The Okta actor ID.
• Request: The authentication request ID.

2c. Tokens Tab

The tokens tab displays all generated tokens with their current status:

• Active: The token is valid and in use.
• Grace Period: A newer token has replaced this one. Both tokens work simultaneously during a 24-hour transition window.
• Expired: The token has passed its expiration date.
• Revoked: The token has been manually revoked and can no longer be used.

Add a Token

Token Name

The name of the token is a way to have a human readable token, which will be displayed across the application instead of a cryptic hash.

Token Expiration

Select the validity period for the generated token. Options: 24 hours, 7 days, 30 days, 90 days, or Never. Shorter expiration periods improve security but require more frequent rotation.

Rotate a Token

Rotating generates a new token with the same name and expiration time as the original. The old token enters a 24-hour grace period during which both tokens are accepted. Use rotation to regularly cycle credentials without downtime.

Revoke a Token

Revoking immediately disables a token. Use this if a token has been compromised or is no longer needed. Revocation is immediate and irreversible.

2d. Configuration Tab

The token authenticates requests between Okta and the Vonage Connector. The configuration is common for every token.

Identity Insights Configuration

Identity Insights is a Vonage API that queries mobile operator databases in real-time to assess the risk profile of a phone number. Within the Okta connector, it operates as a pre-OTP screening layer — checks run before the OTP is sent, and the connector takes action based on the results you configure above.

Each enabled check is billed per request. Number Format & Validity is free. Original Carrier Lookup and Current Carrier Lookup are charged per request. Pricing details are available on the Vonage pricing page.

Identity Insights Overview: https://www.vonage.com/communications-apis/identity-insights/features/  https://developer.vonage.com/en/identity-insights/overview

Toggle "Enable Identity Insights" on, then select the checks to apply.

Select Checks

Checks are available per the selected insight level:

• Number Format & Validity: Validates the phone number format and checks if the number is reachable.
• Original Carrier Lookup: Identifies the carrier the number was originally assigned to. Flags VoIP and virtual numbers.
• Current Carrier Lookup: Identifies the carrier currently serving the number. Detects ported numbers.

Geographic and Channel Filters

These filters restrict OTP delivery based on the phone number’s geographic or network attributes.

• Country Allowlist: Enter ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE). Only numbers associated with these countries will be allowed. Leave empty to allow all countries.

When Number Is Flagged

Choose the action to take when a destination number is flagged during verification checks:

• Block OTP: The OTP is not delivered. You can see the status in ‘Recent OTP Activity’. 
• Flag and Deliver: The OTP is delivered but the event is flagged (amber status) in the dashboard for review.
• Only Log: The check result is logged but no action is taken. The OTP is delivered normally.

Fraud Defender Configuration

Fraud Defender provides delivery-time fraud protection for all OTP traffic sent through the connector. It operates as Layer 2 in the connector's two-layer security model — protecting against SMS pumping, artificially inflated traffic (AIT), and traffic burst attacks during OTP delivery.

Tier Selection

Fraud Defender Advanced is included at no additional cost with Verify and is shown as "Included" in the connector's configuration panel. Fraud Defender Premium is available as a paid upgrade — contact your Account Manager to enable it.

Important: Fraud Defender Advanced is included with your Verify traffic, but advanced protections such as AIT Protection and SMS Burst Protection require separate activation and configuration in the Vonage Dashboard. These protections are not automatically enabled. To set up Fraud Defender for your account, follow the onboarding guide: https://developer.vonage.com/en/fraud-defender/getting-started

What you can configure in the Vonage Dashboard:

• Traffic Rules — Create block and allow rules by country or prefix to control where OTPs can be delivered (available with Fraud Defender Standard, included for all accounts).
• AIT Protection — Automatically detect and block artificially inflated SMS traffic. Three protection levels are available: None (alerts only, no blocking), Standard (blocks high-risk traffic, alerts on the rest), and High (blocks all potentially fraudulent traffic). See: https://developer.vonage.com/en/fraud-defender/guides/ait-protection
• SMS Burst Protection — Set per-country throttling limits to protect against sudden traffic bursts. See: https://developer.vonage.com/en/fraud-defender/guides/sms-burst-protection
• Volumetric Alerts — Automatic alerts when abnormal traffic increases are detected for a country. See: https://developer.vonage.com/en/fraud-defender/guides/volumetric-changes

Rate Limit

The rate limit setting in the connector limits OTP delivery to a maximum number of requests per phone number within a 10-minute window (default: 5). This protects against repeated OTP requests targeting the same number. 

Token Expiration

Select the validity period for the generated token. Options: 24 hours, 7 days, 30 days, 90 days, or Never. Shorter expiration periods improve security but require more frequent rotation.

2d. Record the Generated Token

After configuring security policies and generating the token, record the following details. These are required for Okta configuration in the next step:

• Telephony Webhook URL
• Event Webhook URL
• Auth Header Name
• Token Secret

Step 3: Configure Okta Server

With the connector deployed and a token generated, configure your Okta tenant to route telephony events through the Vonage connector.

3a. Configure the Telephony Inline Hook

Sign in to your Okta Admin Console. Navigate to Workflow › Inline Hooks. Select the “Add Inline Hook”, then “Telephony”

Fill in the hook details:

• Name: Enter a descriptive name (e.g., "Vonage OTP").
• URL: Paste the Telephony Webhook URL from the token generation dialog.
• Authentication field: Paste the Auth Header Name.
• Authentication secret: Paste the Token Secret.

Select "Save".

3b. Configure the Event Hook

Navigate to Workflow › Event Hooks. Select "Create Event Hook".

Fill in the hook details:

• Name: Enter a descriptive name (e.g., "Vonage Events").
• URL: Paste the Event Webhook URL from the token generation dialog.
• Authentication field: Paste the Auth Header Name.
• Authentication secret: Paste the Token Secret (same token as the telephony hook).

In the REQUESTS section, subscribe to the following event type:

• Authentication of user via MFA

Click "Save & Continue".

Step 4: Verify the Connector’s Connectivity

After configuring both the Inline Hook and Event Hook in Okta, verify that the connection between Okta and the Vonage connector is active.

Step 5: Test the Integration

Before going live, verify the integration using Okta’s built-in preview tool.

Prerequisites

Ensure phone authentication is enabled in your Okta org: Security › Authenticators › Phone.

Run a Preview Test

Follow these steps to run a preview test:

• Navigate to Workflow › Inline Hooks.
• Find the telephony inline hook you created and click Actions › Preview.
• In "Configure inline hook request", enter a test user’s information: data.userProfile (a user who has phone as a valid authenticator) and requestType (MFA enrollment, MFA verification, Account unlock, or Password reset).
• Click "Generate request" to build the JSON payload.
• Click "Edit" to modify the request if needed. Replace the default phone number (9876543210) with a real mobile number in E.164 format (e.g., +447700900000).
• Click "View response" to trigger the hook. A successful response will show status: "SUCCESSFUL" with the delivery duration.

⚠️ If the connection between Okta and Vonage fails, Okta will not generate an OTP. Check the connector logs and verify the webhook URL and token are correct.

Step 6: Managing and Rotating Your Authentication Token

The authentication token secures communication between your Okta org and the Vonage connector. As a security best practice, you can rotate this token at any time, either from the Vonage Admin Panel or programmatically via the Token Management API. Rotation issues a new token while keeping the previous one valid for a 24-hour grace period, so you can update your Okta configuration with no interruption to OTP delivery.

Rotate a token - via Admin Panel

1. Log in to the Admin Panel with your admin Vonage account
   
   
    
2. Find the Token List section and identify the token that you would like to rotate
   
   
    
3. Click on the 'Rotate' button to rotate the token
   
   
    
4. Select the 'Confirm' button to rotate the token
   
   
    
5. Your new token will be displayed. Note it down, as it is displayed only once.
   
   
    
6. The new token is now visible on the list. The old token is marked with 'Rotated' status for the 24hr grace period, after which it will be expired.
   
   

Rotate a token - via API

OpenAPI specification + Postman Collection

okta-connector-token-management-v2.0.yaml

Vonage-Okta-API-2.0.postman_collection.json

Authentication

All endpoints are protected with HTTP Basic Auth. Include your credentials in every request.

The value is base64 encoded your Vonage API Key and Vonage API Secret joined with ':'

Basic base64(apiKey:apiSecret)

API Key must be the same key that is the owner of the Okta Connector instance

Fetch the Token List

Before rotating a token, you need its UUID. Use the List Tokens endpoint to retrieve all active tokens and their IDs.

GET /admin/tokens

Returns a map of all tokens associated with the instance. Each entry includes the token's ID, status, claims, and usage counters.

Request

GET /admin/tokens

Authorization: Basic <credentials>

Response — 200 OK

{

  "tokens": {

    "94c624db-d933-446c-be4d-bf35c0dbd13a": {

      "id": "94c624db-d933-446c-be4d-bf35c0dbd13a",

      "name": "Production Okta",

      "truncatedToken": "***",

      "expiresIn": "90d",

      "revoked": false,

      "revokedAt": null,

      "rotatedAt": null,

      "gracePeriodEnds": null,

      "createdAt": "2026-06-17T11:09:30.456Z",

      "expirationDate": "2026-09-15T11:09:30.000Z",

      "lastUsed": "2026-06-20T08:15:00.000Z",

      "smsSuccessCount": 0,

      "voiceSuccessCount": 0,

      "smsErrorCount": 0,

      "voiceErrorCount": 0,

      "smsBlockedCount": 0,

      "voiceBlockedCount": 0

    }

  }

}

Response Fields

Tip — note down the ID: Copy the id value for the token you wish to rotate. You will need it in the next step. The id is linked to a token, so it will always be used to identify a distinct token, but when a new token is generated, both with generate and rotate endpoint, the new token will receive a new id.

Rotate the Token

Token rotation issues a new token with the same claims and a fresh timestamp, and begins the 24hr grace period for the previous token, after which it is invalidated.

POST /admin/rotate-token

Request

POST /admin/rotate-token

Authorization: Basic <credentials>

Content-Type: application/json

{

  "id": "3152b2c3-00b7-4900-b79c-77cfb2663b21"

}

Request Body

Response — 200 OK

{

  "newToken": "<token>",

  "newId": "<uuid>",

  "webhookUrl": "https://<instance-url>/...",

  "authHeaderName": "x-okta-auth"

}

Response Fields

Important Notes

Save the new token immediately. The newToken value is only returned once at rotation time and cannot be retrieved again. Store it securely (e.g. in a secrets manager or Okta webhook configuration) before closing this response.

Record the new ID. The newId returned in the response is the identifier you will need for all future management operations on this token — including subsequent rotations and revocation. Note it down alongside the token.

After Rotation — Update Okta

Once you have rotated the token:

1. Update your Okta Telephony Inline Hook configuration:
   • Go to Inline Hooks and edit the existing hook
     
     
   • Set the authentication field to authHeaderName (default: x-okta-auth).
   • Set the authentication secret value to the new newToken.
     
     
      
2. Update your Okta Event Hook
   • Go to Event Hooks and select the existing hook
     
     
   • Set the authentication field to authHeaderName (default: x-okta-auth).
   • Set the authentication secret value to the new newToken.
     

Failure to update Okta will cause OTP delivery to fail once the old token is invalidated (24hr grace period).

Troubleshooting & Log Access

If OTPs are not being delivered or the Inline Hook is not functioning as expected, start with the following checks:

• Verify credentials: Confirm that the Telephony Webhook URL, Event Webhook URL, Auth Header Name, and Token Secret entered in Okta exactly match the values from the token generation dialog.
• Check hook status: In the Okta Admin Console, navigate to Workflow › Inline Hooks and verify the hook status is Active and verified.
• Review the Dashboard: Check the connector’s Dashboard tab for recent OTP activity. Look for FAILED or FLAGGED events and click the description icon for error details.
• Check Identity Insights flags: If OTPs are being blocked, review whether Identity Insights is flagging the destination number. Consider adjusting the "When number is flagged" action (Block → Flag and Deliver or Only Log) for testing.
• Phone authenticator: Ensure phone authentication is enabled in Okta: Security › Authenticators › Phone.

End-to-End OTP Lifecycle — Tracing a Single Request

Every OTP delivery follows five stages. Each stage has its own log source. When troubleshooting, work through the stages in order — a failure at any stage prevents subsequent stages from executing.

Stage 1: Okta Sends the OTP Request

Where to look: Okta Admin Console › Reports › System Log

When a user triggers an authentication event (login, MFA enrollment, MFA verification, account unlock, or password reset), Okta generates the OTP and sends a Telephony Inline Hook request to the Vonage connector. The Okta System Log captures the outbound hook call, including the target URL, request status, and any errors if the connector was unreachable.

Stage 2: Vonage Connector Receives and Processes the Request

Where to look: Vonage Cloud Runtime › Instances › Your Instance › Logs

The connector instance running on Vonage Cloud Runtime receives the Inline Hook payload from Okta. The VCR instance logs capture the incoming request.

Stage 3: OTP Is Delivered to the End User

Where to look: Vonage Customer Dashboard › Message Logs

Vonage Verify routes the OTP through the appropriate channel (SMS or Voice) via the Messages API. The delivery event — including message status, carrier information, and any delivery errors — appears in the Vonage Customer Dashboard message logs.

What to check:

• Message status: Look for the outbound message record. A "delivered" status confirms the OTP reached the carrier network. A "failed" or "rejected" status indicates a delivery problem.
• Channel and sender: Verify the correct channel (SMS/Voice) and sender ID were used.
• Fraud Defender: If the message does not appear at all, Fraud Defender may have blocked the request during delivery (e.g., SMS pumping detection or geographic permissions). In this case, no message is sent and no delivery charge is incurred.
• Error codes: If delivery failed, note the provider error code. Reference the Vonage error codes documentation for details: developer.vonage.com/en/api-errors/messages

Stage 4: User Enters OTP → Okta Validates → Event Hook Fires

Where to look: Connector Admin Dashboard › Recent Auth Events

After the end user receives and enters the OTP in Okta’s interface, Okta validates the code. As the customer has configured the Event Hook (as described in Step 3b), Okta sends an asynchronous authentication event to the connector indicating whether the verification succeeded or failed. This event is what enables the connector to know that the OTP was successfully verified and the Verify conversion fee gets charged.

What to check:

• Event received: In the connector’s Admin Dashboard, navigate to the Recent Auth Events section. Look for the authentication event corresponding to your test.
• Event type: The event should show "user.authentication.auth_via_mfa" for a successful MFA verification.
• Factor and outcome: Confirm the factor is correct (e.g., SMS_FACTOR) and the outcome shows SUCCESS. A FAILURE outcome means the user entered an incorrect OTP or the verification timed out.
• Token: The truncated token identifier should match the token you configured in Okta.

Stage 5: Verify Conversion Recorded

Where to look: Vonage Customer Dashboard › Verify Logs

Once the connector receives the successful authentication event from Okta (Stage 4), it confirms the conversion with Vonage Verify. This marks the Verify request as successfully converted — meaning the OTP was delivered, received, entered correctly, and validated. The Verify conversion fee is applied at this point.

What to check:

• Conversion status: In the Vonage Customer Dashboard Verify logs, locate the Verify request (by request ID from Stage 2). Confirm the status shows as "converted" or "successful".
• Conversion fee: The Verify conversion fee is applied when the request transitions to converted status. This is the primary platform-level revenue event for each successful OTP.
• Missing conversion: If the Verify log shows the OTP was delivered but never converted, check Stage 4. The most common causes are: the Event Hook is not configured in Okta, the hook failed to fire, or the user did not enter the OTP within the allowed time window.

Error Codes & Identity Insights Reference

When an OTP request is blocked, fails, or is flagged, the connector returns a structured error visible in the Dashboard's Recent OTP Activity section. Click the eye icon next to any BLOCKED, FAILED, or FLAGGED entry to view the error detail. Each error contains a Code/Message and, for Identity Insights checks, a Sub-code explaining the specific reason.

Use the tables below to identify the cause and determine the corrective action.

Connector Error Codes

This table covers all error codes returned by the connector. The Response Type indicates how Okta interprets the response: claim_violation tells Okta the delivery was intentionally rejected (Okta may fall back to its native provider if configured), failure indicates the delivery could not be completed, and unexpected_failure indicates an unhandled error.

Identity Insights Sub-Codes

When the error message is "Identity Insight flagged: <reasons>", the reasons field contains one or more of the sub-codes below. Multiple sub-codes may appear separated by commas if several checks flagged the same number.

Quick Reference: Where to Look at Each Stage

How to Get Help

Best way (recommended): Vonage Help Center

https://api.support.vonage.com/hc/en-us/requests/new

Select the form titled "Using Vonage Connector” and then select your connector -> “Using Vonage Protection Suite for Okta" so the ticket is routed directly to the Okta Connector support group.

What to include (for faster resolution):

For End Users — OTP Delivery Experience

End users do not need to perform any configuration. Once the administrator has completed the setup in Section 6, the Vonage connector handles OTP delivery transparently. From the end user’s perspective, the authentication flow remains identical to their existing Okta experience:

• The user initiates an authentication flow in Okta (login, MFA enrollment, MFA verification, account unlock, or password reset).
• Okta prompts the user to verify via phone. The user selects SMS or Voice.
• The OTP is delivered to the user’s phone via the Vonage connector (via Vonage Verify).
• The user enters the OTP in Okta’s interface.
• Okta validates the OTP and completes the authentication.

The Vonage connector operates entirely behind the scenes. If Voice Call Fallback is enabled, the connector automatically retries via voice call if SMS delivery fails — the user receives the OTP through the fallback channel without any additional action.