OTP API Overview

The OTP (One-Time Password) API enables you to implement secure multi-channel verification for user authentication, phone/email verification, and two-factor authentication (2FA) workflows.

Why Use the OTP API?

• 🔐 Multi-Channel Support - Send OTPs via Email, SMS, and WhatsApp
• ⚡ Fast & Secure - Industry-standard bcrypt hashing with configurable expiry
• 🎯 Flexible Verification - Verify single or multiple channels in one session
• 🧪 Sandbox Mode - Test your integration without sending real messages
• 🔄 Session Management - Built-in rate limiting and attempt tracking
• 📊 Auto-Contact Creation - Optionally add verified contacts to your database
• ⏱️ Configurable - Set custom OTP length, expiry, and attempt limits

Core Concepts

OTP Session

An OTP session is created when you send an OTP. It manages:

• Multiple Channels: Send OTP to email, SMS, and WhatsApp simultaneously
• Verification State: Track which channels have been verified
• Security: Rate limiting, attempt tracking, and automatic expiration
• Metadata: Store custom data for your application logic

Channels

Channel	Description	Use Case
Email	Send OTP via email	Email verification, account recovery
SMS	Send OTP via SMS	Phone verification, 2FA
WhatsApp	Send OTP via WhatsApp	Modern 2FA, international users

Verification Flow

1. Send OTP - Create session and send OTP to one or more channels
2. User Receives - OTP delivered via Email, SMS, or WhatsApp
3. User Submits - User enters OTP code in your application
4. Verify OTP - Validate the code and mark channel(s) as verified
5. Session Complete - Use verified session data in your application

Key Features

Multi-Channel Verification

Send OTPs to multiple channels in a single request:

{
  "channels": ["email", "sms", "whatsapp"],
  "recipients": {
    "email": "user@example.com",
    "sms": "+1234567890",
    "whatsapp": "+1234567890"
  }
}

Progressive Verification (Verify Separately)

Powerful Feature: Verify different channels at different times!

• Send OTP to multiple channels (email + SMS + WhatsApp)
• User verifies WhatsApp first → Session becomes PARTIAL
• Later, user verifies email → Session progresses
• Each channel maintains its own verified state
• All within the same expiry window (e.g., 10 minutes)

Example:

1. Send to Email + SMS (10:00 AM)
2. User verifies SMS (10:03 AM) ✅
3. User verifies Email (10:07 AM) ✅
4. Session fully verified before expiry (10:10 AM)

Flexible Verification Options

Choose verification strategy based on your needs:

• All Channels Required: User must verify all channels (progressive or simultaneous)
• Any Channel: User can verify any one channel
• Specific Channels: User must verify specific channels

Security Features

• Bcrypt Hashing: OTPs are hashed before storage
• Configurable Expiry: Default 10 minutes, customizable per request
• Attempt Limiting: Configurable max attempts (default 3)
• Rate Limiting: Prevent OTP spam and abuse
• Auto-Expiration: Sessions automatically expire after time limit

Sandbox Mode

Test your integration without sending real messages:

{
  "sandbox_mode": true
}

In sandbox mode:

• OTPs are returned in the API response
• No messages are actually sent
• No wallet charges are applied
• Sessions are marked as sandbox for filtering

API Endpoints

Endpoint	Method	Description
/api/v1/otp/send	POST	Send OTP to one or more channels
/api/v1/otp/verify	POST	Verify OTP code for a session
/api/v1/otp/resend	POST	Resend OTP for an existing session
/api/v1/otp/sessions	GET	List OTP sessions (with filtering)

Common Use Cases

1. Email Verification

# Send OTP to email
POST /api/v1/otp/send
{
  "channels": ["email"],
  "recipients": {
    "email": "newuser@example.com"
  },
  "metadata": {
    "purpose": "email_verification",
    "user_id": "user_12345"
  }
}

# Verify OTP
POST /api/v1/otp/verify
{
  "token": "eyJhbGc...",
  "otps": {
    "email": "123456"
  }
}

2. Phone Verification (SMS + WhatsApp)

# Send OTP to both SMS and WhatsApp
POST /api/v1/otp/send
{
  "channels": ["sms", "whatsapp"],
  "recipients": {
    "sms": "+1234567890",
    "whatsapp": "+1234567890"
  },
  "metadata": {
    "purpose": "phone_verification"
  }
}

# User can verify via either channel
POST /api/v1/otp/verify
{
  "token": "eyJhbGc...",
  "otps": {
    "whatsapp": "654321"
  }
}

3. Two-Factor Authentication (2FA)

# Send OTP for 2FA
POST /api/v1/otp/send
{
  "channels": ["sms"],
  "recipients": {
    "sms": "+1234567890"
  },
  "config": {
    "otp_length": 6,
    "expiry_minutes": 5,
    "max_attempts": 3
  },
  "metadata": {
    "purpose": "2fa_login",
    "user_id": "user_12345"
  }
}

Configuration Options

OTP Configuration

Option	Type	Default	Description
otp_length	number	6	Length of OTP code (4-8 digits)
expiry_minutes	number	10	Session expiry time in minutes
max_attempts	number	3	Maximum verification attempts

Session Metadata

Store custom data with each session:

{
  "metadata": {
    "user_id": "user_12345",
    "purpose": "email_verification",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  }
}

Best Practices

1. Security

• Never expose OTPs: Don't log or store OTPs in plain text
• Use HTTPS: Always use secure connections
• Implement rate limiting: Limit OTP requests per user/IP
• Short expiry times: Use 5-10 minutes for sensitive operations
• Monitor attempts: Block users after suspicious activity

2. User Experience

• Clear instructions: Tell users where to find the OTP
• Resend option: Allow users to request a new OTP
• Multi-channel fallback: Offer alternative channels if one fails
• Auto-fill support: Use standard formats for OTP input
• Clear error messages: Help users understand what went wrong

3. Integration

• Use metadata: Store context for later retrieval
• Handle errors gracefully: Provide helpful error messages
• Test with sandbox: Use sandbox mode during development
• Auto-contact creation: Enable add_contact for verified users
• Session management: Clean up expired sessions regularly

Error Handling

Common error scenarios:

Error	Cause	Solution
Invalid OTP	Wrong code entered	Allow retry within attempt limit
OTP expired	Session timed out	Send new OTP
Max attempts exceeded	Too many failed attempts	Lock session, send new OTP
Insufficient balance	Not enough wallet credits	Add credits to wallet
Invalid recipient	Malformed email/phone	Validate input before sending

Rate Limits

To prevent abuse, OTP endpoints have rate limits:

• Per User: 5 OTP sends per 5 minutes
• Per Session: 3 verification attempts
• Per IP: 20 OTP sends per hour

Next Steps

• Send OTP - Learn how to send OTPs
• Verify OTP - Learn how to verify OTPs
• Authentication - Set up API authentication