Verify API

Overview

The Verify API handles phone and email verification for user signup, two-factor authentication, and number confirmation. The API provides a secure, channel-agnostic way to verify user identities through one-time passwords (OTP).

How it works

The verification flow consists of three main endpoints:

1. Start - Send an OTP code to a phone number or email address
2. Check - Verify the code submitted by the user
3. Status - Get the current state of a verification

Key features

• Multiple channels: Send OTP codes via SMS, voice call, WhatsApp, or email
• Secure storage: Codes are bcrypt-hashed and never stored in plaintext
• Time-limited: Codes expire after 10 minutes
• Attempt limiting: Maximum of 5 verification attempts per code
• Rate limiting: 5 OTP requests per phone number per hour
• Flexible code length: Support for 4-8 digit codes (default: 6)
• Custom templates: Use your own message templates with code placeholder

Authentication

All Verify API requests require:

• Authorization header: Authorization: Bearer tvx_sk_live_...
• Tenant ID header: X-Tenant-ID: acc_...

Base URL

https://api.tryvox.io

Quick start

# 1. Start verification
curl -X POST https://api.tryvox.io/v1/verify/start \
  -H "Authorization: Bearer tvx_sk_live_..." \
  -H "X-Tenant-ID: acc_123" \
  -H "Content-Type: application/json" \
  -d '{"to": "+919876543210", "channel": "sms", "app_name": "MyApp"}'

# 2. Check the code
curl -X POST https://api.tryvox.io/v1/verify/check \
  -H "Authorization: Bearer tvx_sk_live_..." \
  -H "X-Tenant-ID: acc_123" \
  -H "Content-Type: application/json" \
  -d '{"verification_id": "ver_abc123", "code": "123456"}'

Security considerations

• All OTP codes are hashed using bcrypt before storage
• Codes automatically expire after 10 minutes
• Rate limiting prevents abuse (5 OTPs per phone/hour)
• Maximum 5 verification attempts per code
• Failed verifications are logged for audit purposes

Next steps

• Start Verification - Send OTP codes
• Check Verification - Verify user-submitted codes
• Get Status - Query verification state