Vonage Protection Suite for PingOne

Table of Contents

1. Introduction
2. Key Benefits
3. Prerequisites
4. Architecture Overview
5. User Roles
6. For Admin User — Installation & Configuration Guide
   Step 1: Deploy the Connector on Vonage Cloud Runtime
   Step 2: Configure the Connector (Admin Application)
   Step 3: Configure PingOne
   Step 4: Verify the Connector’s Connectivity
   Step 5: Test the Integration
   Step 6: Managing and Rotating Your Authentication Token
   Troubleshooting & Log Access
   How to Get Help
7. For End Users — OTP Delivery Experience

Introduction

The Vonage Protection Suite for PingOne is a self-service, no-code connector built on Vonage Cloud Runtime (VCR). It integrates directly into your PingOne environment as a Custom Notification Provider to deliver One-Time Passwords (OTPs) through SMS and Voice channels, powered by Vonage Verify.

Before any OTP is delivered, the connector can execute optional pre-delivery security checks through Identity Insights, including number validation and carrier lookups, screening destination numbers against mobile operator databases to block fraud before it happens.

During OTP delivery, Vonage Fraud Defender provides an additional layer of protection with SMS pumping detection, geographic permissions, and velocity controls.

This creates a two-layer security model:

• Layer 1 - Identity Insights (Pre-OTP): Screens the destination number before the OTP is sent. Flags or blocks compromised numbers, saving delivery costs.
• Layer 2 - Fraud Defender (During OTP): SMS pumping protection, geographic permissions, and velocity controls during delivery. Included free with Verify.

The connector is deployed on Vonage Cloud Runtime and distributed through the Vonage Cloud Runtime (VCR) Marketplace. Enterprises discover, install, configure their PingOne environment, and are live, without any Vonage operational intervention.

Use of the Vonage Protection Suite for PingOne is subject to the Vonage Terms of Use and Connector Supplemental Terms.

Key Benefits

• Self-service, no-code setup: Deploy and configure the connector through Vonage Cloud Runtime Marketplace. No developer resources or custom middleware required.
• OTP delivery via Vonage Verify: Intelligent routing, automatic SMS-to-Voice fallback, and global reach across 200+ countries with automatic sender ID management.
• Two-layer fraud intelligence: Pre-OTP number screening (Identity Insights) combined with delivery-time fraud protection (Fraud Defender), a combination no other provider currently offers in their PingOne integration.
• Native PingOne failover support: The connector plugs into PingOne Notification Policies, so administrators can set provider priority, per-country routing, and delivery limits using standard PingOne controls.
• Speed to value: Self-service onboarding enables signup to the first OTP delivery in minutes. Production-ready MFA in days, not months.
• Token-based security: Secure, rotatable, named authentication tokens secure every OTP delivery request. 24-hour grace period for seamless rotation.
• Real-time monitoring: Built-in dashboard with OTP delivery counters, recent activity logs, and authentication event tracking.
• Custom OTP message templates: Per-locale and per-channel message customisation so end users receive OTPs in their local language with your brand wording.

Prerequisites

• An active PingOne environment with the PingOne SSO and PingOne MFA services included in the environment's Bill of Materials (Environment > Properties).
• Admin access to the PingOne admin console with permissions to configure Senders, Notification Policies, MFA policies, Authentication policies, and Webhooks.
• A Vonage API account with an API Key.
• Access to the Vonage Customer Dashboard and Vonage Cloud Runtime (Advanced Subscription).

Note: The Vonage Cloud Runtime Advanced tier is required for production deployments of this connector to ensure reliable handling of peak authentication volumes. This subscription is activated by your Vonage Customer Success Associate (CSA) as part of the deployment process. No action is required from the customer; your CSA will handle the activation before your connector instance goes live.

Architecture Overview

The connector sits between PingOne and Vonage's Communication APIs. PingOne calls the connector's delivery endpoints, configured as a Custom Notification Provider under Settings > Senders, to orchestrate OTP delivery. PingOne remains the verification authority throughout the flow: it generates the OTP, passes it to the connector for delivery, and validates it when the user enters it. 

The data flow works as follows:

1. PingOne generates a one-time password and calls the Vonage connector's SMS or Voice delivery endpoint (configured as a Custom Notification Provider), passing the OTP and the customer's phone number.
2. If Identity Insights is enabled, the connector screens the destination number against mobile operator databases (number validity, carrier lookup). Based on the result, the connector can block, flag-and-deliver, or proceed.
3. The connector sends the OTP via Vonage Verify, which handles intelligent channel routing (SMS/Voice), automatic fallback, sender ID management, and Fraud Defender protections.
4. The end user receives the OTP on their phone and enters it in PingOne's authentication interface.
5. PingOne validates the OTP and grants access. If a PingOne Webhook is configured (Step 3e), PingOne posts the verification outcome event to the connector asynchronously, enabling end-to-end conversion visibility.

Two-Layer Fraud Intelligence Model

User Roles

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

For Admin User - Installation and Configuration Guide

This section walks the administrator through the complete setup process, from deploying the connector on Vonage Cloud Runtime to configuring PingOne 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 PingOne from the VCR Marketplace.

1. 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 PingOne" application.

2. Fill in the Configuration Details

• Region and instance name: Choose the region for your instance and provide a unique, concise name.

  

3. Configuration Type

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

• 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 name.

• 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 name: Token name that was set on creation.

Recent Auth Events

The last 20 successful verification events received from PingOne via the configured Webhook (see Step 3e), showing Timestamp, Token, Event type, Outcome, User, and Correlation reference. The connector records OTP Check Success events only; failed or unrelated events are not stored.

• Timestamp: When the event was published by PingOne.
• Token name: Token name that was set on creation.
• Event: The PingOne event type (OTP Check Success).
• Outcome: SUCCESS. The connector filters to successful OTP verifications; other outcomes are not recorded.
• User: The PingOne user identifier.
• Correlation: The reference used to correlate the event back to the original OTP delivery.

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 PingOne and the Vonage connector. The configuration is common for every token on the instance.

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 PingOne 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.

Each enabled check is billed per request. Number Format and 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/  and  https://developer.vonage.com/en/identity-insights/overview

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

Select Checks

• Number Format and 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 user within a 10-minute window (default: 5 requests per user per 10 minutes). This protects against toll fraud and repeated OTP requests targeting the same user.

Note: PingOne Notification Policies independently enforce their own delivery limits, cooldown rules, and per-country routing. Disable any PingOne-side velocity rules that duplicate the connector's rate limit, so that a blocked delivery always has a single, unambiguous cause.

Channel Timeout

The channel timeout controls how long the connector waits on the first delivery channel before moving on, configurable between 15 and 900 seconds. When Voice Call Fallback is enabled, this is the window after which an undelivered SMS triggers the automatic voice call.

Custom OTP Message Templates

By default, the connector uses Vonage's standard OTP message template for all SMS and voice deliveries. Custom OTP Message Templates allow you to replace this default with your own message body, giving you control over the wording and language of the OTP notification your end users receive. This is useful for organisations operating across multiple regions, where delivering the OTP message in the user's local language improves completion rates, or where brand-specific messaging is required. Once configured, the active template applies to all OTP deliveries on this connector instance.

Enable Custom Templates

Custom Template Management is disabled by default on Vonage accounts and must be enabled by contacting your Vonage Account Manager or Vonage Support. Once enabled, you can create and manage templates via the Admin Application's Templates section.

To make a template active for this connector instance, go to Configuration / Preferred Template and choose a template.

Configure a Template

Templates have two layers:

• Template: a named container. Name is a human-readable label for the template. If "Is default" is checked, this template is used when no preferred template is set.
• Fragment: the per-channel, per-locale message body. Configure the Delivery channel (SMS or Voice Call), the Locale, and the Text (a message body with placeholders). See: https://developer.vonage.com/en/verify/guides/custom-templates#creating-fragments

Available placeholders for text:

• ${code}: Required. The OTP the user must enter.
• ${brand}: Replaced by the brandName configured for this instance.
• ${time-limit}: Numeric expiry time of the code.
• ${time-limit-unit}: Unit of expiry (e.g. minutes).

Example: "Your ${brand} verification code is ${code}. Valid for ${time-limit} ${time-limit-unit}."

Character limits follow standard SMS encoding rules:

• GSM-7 (standard Latin): 160 chars per single SMS, 153 per part if concatenated.
• UCS-2 (Arabic, Chinese, Cyrillic, etc.): 70 chars per single SMS, 67 per part if concatenated.

Templates are global to the instance: one preferred template applies to all tokens on the VCR instance. Individual tokens do not have their own template overrides.

Supported Languages

Fragments are matched by the locale field (e.g. en-us). If the locale is not provided in the verify request, Vonage attempts to detect it from the phone number prefix or falls back to en-us. The link below shows the locales available for SMS and Voice Call fragments: https://developer.vonage.com/en/verify/guides/verify-v2-languages#verify-languages 

Locales marked default+custom have Vonage-built default messages and support custom overrides; locales marked custom only require a custom fragment; no built-in Vonage message exists for them.

What Happens Without a Custom Template

If no preferred template is set (or it is set to none), Vonage's built-in default template is used for the channel and locale. The fallback order Vonage applies is:

1. Fragment matching the requested locale in the preferred template.
2. Fragment in the instance's default template matching the locale.
3. Vonage's built-in default message for that locale and channel.
4. Vonage's built-in English (en-us) message if no locale match is found.

For locales marked custom only, there is no Vonage built-in fallback: a custom fragment is required or delivery will fail for that locale.

2e. Record the Generated Details

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

• Sender Endpoint URL (a single endpoint used for both SMS and Voice; the delivery channel is carried in the request body)
• Destination Webhook URL (for PingOne verification events) 
• Authentication Token (the credential PingOne presents on every request)
• Auth Header Name (only needed if you use the Custom Header authentication scheme; default x-ping1-auth)

• Request Body Templates (SMS and Voice) as displayed in the token generation dialog.
  
  

Note: The Authentication Token is displayed only once at creation. Store it securely before closing the dialog.

Step 3: Configure PingOne

With the connector deployed and a token generated, configure your PingOne environment to route OTP delivery through the Vonage connector. This involves four parts: adding the Custom Notification Provider, linking it in a Notification Policy, enabling SMS and Voice in your MFA configuration, and (optionally but recommended) configuring a Webhook to return verification events to the connector.

3a. Add Vonage as a Custom Notification Provider

Sign in to your PingOne admin console and confirm you are in the correct environment. Navigate to Settings > Senders and click the "+" icon to add a new sender.

Select SMS/Voice as the Sender Type, then select "Custom Provider" from the Provider Type dropdown.

Fill in the provider details using the values recorded in Step 2e:

• Name: Enter a descriptive name (e.g., "Vonage Protection Suite").
• Authentication: Select Bearer Token (recommended) and paste the Authentication Token as the bearer value. The connector supports all four authentication schemes offered by PingOne's Custom Provider: Bearer Token, HTTP Basic, OAuth2 Client Credentials, and Custom Header. If you use the Custom Header scheme, enter the Auth Header Name as the header key and the Authentication Token as the header value.
• SMS configuration: Set the request method to POST, paste the OTP Delivery Endpoint URL, select raw JSON as the body format, and paste the SMS request body template. The body template uses PingOne's dynamic variables, including ${to} (recipient number), ${otp} (the generated passcode), and ${message} (full message text). Put this body for SMS message:

{ 
 "phoneNumber": "${to}", 
 "message": "${message}", 
 "otpCode": "${otp}", 
 "locale": "${locale}", 
 "userId": "${user.username}", 
 "channel": "sms" 
}

NOTE: For Send Test SMS or Voice replace the values following fields: 

• Voice configuration: Set the request method to POST, paste the same OTP Delivery Endpoint URL (the connector uses one delivery endpoint for both channels; the requested channel is identified in the request body), and paste the Voice request body template using the same dynamic variables.

{ 
 "phoneNumber": "${to}", 
 "message": "${message}", 
 "otpCode": "${otp}", 
 "locale": "${locale}", 
 "userId": "${user.username}", 
 "channel": "voice" 
}

• Sender phone numbers: Add the phone number(s) to use as sender IDs and mark their capabilities (SMS, Voice) as applicable. Check the "Plus sign for numbers" setting so number formats match what the connector expects (E.164).

  

  
   

  

  
  

Click Save.

Reference: Configuring a custom notification provider for PingOne

3b. Link the Vonage Provider in a Notification Policy

Note: This step must be completed before configuring MFA policies. PingOne locks the SMS and Voice checkboxes in MFA policies until a notification policy has a configured sender assigned for those channels.

1. In the PingOne admin console, go to User Experience > Notification Policies.
2. Edit the Default policy or click + Add Policy to create a new one.
3. Under SMS Provider, select your Vonage custom provider from the dropdown.
4. Under Voice Provider, select your Vonage custom provider from the dropdown.
5. Set provider priority and any per-country routing rules as needed.
6. Click Save.
   

Reference: Notification Policies

3c. Enable SMS and Voice in MFA Settings and MFA Policy

Configure MFA Settings

1. Go to Authentication > MFA and open MFA Settings (gear icon).
2. Set "MFA status for new users" to Enabled so MFA is automatically enabled for newly created users.

3. Click Save.

   

Configure the MFA Policy

The SMS and Voice checkboxes are unlocked after completing Step 3b.

1. Go to Authentication > MFA > MFA Policies.
2. Edit the Default MFA Policy (pencil icon) or create a new one.
3. Under Allowed Authentication Methods, check SMS and Voice.
4. Under Notification Policy, select the notification policy you configured in Step 3b.

5. Click Save.

   
   
   

Note: If SMS/Voice are still locked, go back to Step 3b and verify the Vonage custom provider is selected as the sender in the notification policy. Also confirm that PingOne MFA is included in your environment's Bill of Materials (Environment > Properties).

References: Configuring an MFA policy  |  Configuring MFA settings

3d. Require MFA in Your Authentication Policy

Ensure an authentication policy requires MFA after login so the OTP flow is triggered:

1. Go to Authentication > Authentication and edit the existing Multi_Factor policy or add a new policy.
2. Confirm Step 1 (Login) is configured with username and password.
3. Add a second step of type Multi-factor Authentication and select the MFA policy from Step 3c.
4. Assign this authentication policy to the applications that should require phone-based MFA.

Reference: Adding a multi-factor authentication step

3e. Configure a PingOne Webhook for Verification Events (Recommended)

The custom provider you configured handles delivery; the Webhook handles the verification outcome signal coming back. PingOne generates and validates the OTP itself. When the user enters the correct code, PingOne records the OTP check outcome as an audit event and posts it asynchronously to the Webhook URL. The connector receives that event and correlates it back to the original delivery, enabling the Recent Auth Events view and end-to-end conversion tracking. This runs after delivery, is optional, and is enabled by the customer.

1. In the PingOne admin console, confirm you are in the correct environment, then open Integrations > Webhooks. Click Add Webhook.
2. Enter a Name (for example, "Vonage Verification Events").
3. Set the Destination URL to the Event Webhook URL recorded in Step 2e. The endpoint accepts HTTPS POST requests.
4. Choose the Format: select Ping Activity Format. This is the generic JSON format, the same one the PingOne API uses for audit activities, and is the correct choice for the Vonage endpoint.
5. Under Event Types, use the search box to find and select OTP Check Success. This is the event the connector consumes to confirm verification. Other event types are ignored by the connector (and safely acknowledged), so subscribing to additional events only adds noise.
6. Optionally, under Additional Conditions (tags, applications, populations), narrow the scope so only the relevant verification events are sent. This reduces noise.
7. Optionally set a Payload Limit (by size in KB or by number of events). If unset, the default is up to 500 events per payload.

8. Save and enable the Webhook.

   

   

   

   
   

References: Creating or editing a webhook  |  Audit reporting events

Step 4: Verify the Connector's Connectivity

After configuring the Custom Notification Provider and the Webhook in PingOne, verify that the connection between PingOne and the Vonage connector is active:

• Test SMS from PingOne: In Settings > Senders, open the Vonage custom provider and use the built-in test option to send a test SMS to a real phone number. Confirm the message is received.
• Check the connector Dashboard: The test delivery appears in the connector's Recent OTP Activity with a SUCCESS status.

• Check the Webhook status: In Integrations > Webhooks, confirm the Vonage Webhook shows as enabled and healthy.

  

Step 5: Test the Integration

Before going live, verify the full end-to-end authentication flow with a test user.

Prerequisites

• An application in the environment (Connections > Applications) with the MFA-enabled authentication policy from Step 3d assigned, or use the PingOne Self-Service portal.

• A test user (Directory > Users) with MFA enabled and a real phone number that can receive SMS and calls.

  

Option A: Via Browser (Recommended)

1. Open an incognito/private browser window.
2. Navigate to the PingOne authorization URL for your test application: https://auth.pingone.com/{environmentId}/as/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope=openid. Replace {environmentId}, {clientId}, and {redirectUri} with the values from your application's Overview and Configuration tabs.
3. Enter the test user's username and password on the PingOne login page.
4. PingOne prompts for MFA. Select SMS or Voice. If the user has not enrolled a phone number for MFA yet, PingOne prompts for enrollment; enter the phone number.
5. Vonage delivers the OTP via the custom provider you configured.
6. Enter the OTP code on the PingOne screen. On success, you are redirected to the application's redirect URI with an authorization code.

Option B: Via PingOne Self-Service Portal

1. Navigate to the PingOne self-service URL for your environment: https://apps.pingone.com/{environmentId}/myaccount/.
2. Sign in with the test user credentials.
3. PingOne prompts for MFA. Complete the MFA challenge; Vonage delivers the OTP.

Confirm the Results

• Vonage Dashboard: Go to Logs > SMS Logs (or Voice Logs) and confirm the OTP message was sent to the test user's phone number, noting delivery status, latency, and carrier information.
• Connector Dashboard: Confirm the delivery appears in Recent OTP Activity, and, if the Webhook is configured, the OTP Check Success event appears in Recent Auth Events.

This confirms the end-to-end flow: PingOne > Vonage connector > SMS/Voice delivery > user enters OTP > PingOne validates > verification event returned to Vonage.

Warning: If the connection between PingOne and Vonage fails, the OTP will not be delivered. Check the connector logs and verify the endpoint URLs, auth header, and token entered in the PingOne sender configuration are correct.

Step 6: Managing and Rotating Your Authentication Token

The authentication token secures communication between your PingOne environment 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 PingOne 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 and Postman Collection

pingone-connector-token-management-v1.0.yaml

pingone-connector-token-management-v1.0.postman_collection.json

Authentication

All endpoints are protected with HTTP Basic Auth. Include your credentials in every request. The value is your Vonage API Key and Vonage API Secret joined with ':' and base64 encoded:

Basic base64(apiKey:apiSecret)

Warning: The API Key must be the same key that is the owner of the PingOne 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, name, status, claims, and usage counters.

Tip: Copy the id value for the token you wish to rotate; you will need it in the next step. The id always identifies a distinct token. When a new token is generated (via generate or rotate), the new token receives 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 body: { "id": "<token-uuid>" } where id is the UUID of the token to rotate, obtained from GET /admin/tokens.

The response (200 OK) returns the new signed token and the identifier of the newly issued token. The token value is returned once and never again. The OTP Delivery Endpoint URL, Event Webhook URL, and Auth Header Name do not change on rotation; they can be retrieved at any time from GET /admin/config. Refer to the OpenAPI specification for the complete response schema.

Warning: Save the new token immediately. The newToken value is only returned once at rotation time and cannot be retrieved again. Store it securely before closing the response. Also record the newId; it is the identifier you will need for all future management operations on this token, including subsequent rotations and revocation.

After Rotation - Update PingOne

Once you have rotated the token, update your PingOne configuration:

1. Go to Settings > Senders and edit the Vonage custom provider. In the Authentication section, update the credential to the new token: the bearer value if you use Bearer Token, or the custom header value if you use the Custom Header scheme.

   

2. If your Webhook authenticates with the token, go to Integrations > Webhooks, open the Vonage Webhook, and update the credential to the new token.
   

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

Troubleshooting and Log Access

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

• Verify credentials: Confirm that the OTP Delivery Endpoint URL, Event Webhook URL, authentication scheme, and Authentication Token entered in PingOne exactly match the values from the token generation dialog.
• Check the Notification Policy: Confirm the Vonage custom provider is selected as the SMS and Voice provider in the Notification Policy, and that the MFA policy is linked to that Notification Policy. Check provider priority if multiple providers are configured.
• 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.
• Check number format: PingOne uses E.164 by default. Verify the "Plus sign for numbers" setting in your custom provider configuration matches what the connector expects.
• MFA configuration: Ensure SMS and Voice are enabled in the MFA policy, the MFA policy is linked to the authentication policy, and the user has MFA enabled.

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: PingOne Sends the OTP Delivery Request

Where to look: PingOne Admin Console > Monitoring > Audit

When a user triggers an authentication event requiring phone MFA, PingOne generates the OTP and calls the Vonage connector's delivery endpoint via the configured Custom Notification Provider. The PingOne audit log captures the notification lifecycle events, including whether the outbound request to the provider was made and any errors if the provider 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 delivery request from PingOne. The VCR instance logs capture the incoming request, the Identity Insights check outcome, and the call to the Verify API.

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). 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, PingOne Validates, Webhook Fires

Where to look: Connector Admin Dashboard > Recent Auth Events, and PingOne > Integrations > Webhooks (delivery status)

After the end user receives and enters the OTP in PingOne's interface, PingOne validates the code and records the OTP check outcome as an audit event. If the Webhook is configured (Step 3e), PingOne posts the event asynchronously to the connector. This event is what enables the connector to know that the OTP was successfully verified, and the Verify conversion is registered.

What to check:

• Event received: In the connector's Admin Dashboard, navigate to the Recent Auth Events section. Look for the event corresponding to your test.
• Event type: The event should show OTP Check Success for a successful MFA verification.
• Outcome: Confirm the outcome shows SUCCESS. The connector records successful verifications only; if the user entered an incorrect OTP or the verification timed out, no event appears in Recent Auth Events.

• Webhook delivery: If no event was received, check the Webhook's delivery status in PingOne, confirm the Webhook is enabled, the Destination URL is reachable over HTTPS, and the subscribed Event Types include the OTP check events.

  

Stage 5: Verify Conversion Recorded

Where to look: Vonage Customer Dashboard > Verify Logs

Once the connector receives the successful verification event from PingOne (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.

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".

• Missing conversion: If the Verify log shows the OTP was delivered but never converted, check Stage 4. The most common causes are: the Webhook is not configured in PingOne, the Webhook failed to fire, or the user did not enter the OTP within the allowed time window.

  

Error Codes and 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

Every 400, 403, and 500 response from the connector uses a single error envelope containing an errorCode, a human-readable errorSummary, an errorId (the request correlation identifier, which maps directly to the connector's logs and can be quoted to Vonage Support), and an errorCauses array that identifies exactly which field failed validation and why.

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

Quick Reference: PingOne Navigation Paths

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 PingOne" so the ticket is routed directly to the PingOne 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 PingOne experience:

• The user initiates an authentication flow in a PingOne-protected application (login, MFA enrollment, or self-service account access).
• PingOne 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 PingOne's interface.
• PingOne 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.