Verify OTP

Verify an OTP code that was sent via the `/auth/send-otp` endpoint

This endpoint validates the OTP code against the stored record, checking expiry, attempt limits, and code correctness. On successful verification, the rate limiter is cleared

Required Scope

messages:send

Rate Limiting

10 verification attempts per minute per phone number per tenant

Rate limit key: otp-verify:{tenant_id}:{phone}

Rate limit clears automatically on successful verification

Returns retry_after seconds when limit exceeded

Verification Flow

Phone number is cleaned (non-numeric chars removed except +)

Rate limit check (10 attempts/min)

Active OTP lookup for phone & purpose combination

Max attempts check (default: 5 attempts per OTP)

Expiry check

Code comparison

On success: OTP marked as verified, rate limiter cleared

Error Scenarios

OTP_NOT_FOUND No active OTP for this phone number and purpose

MAX_ATTEMPTS_EXCEEDED Too many failed verification attempts (default: 5). Must request new OTP

OTP_EXPIRED OTP has passed its expiry time. Must request new OTP

INVALID_CODE Wrong code entered. Returns attempts_remaining count

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Header Params

Body Params application/jsonRequired

Example

{
    "phone": "+201XXXXXXXXX",
    "code": "123456",
    "purpose": "authentication"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

Example

{
    "success": true,
    "data": {
        "phone": "201XXXXXXXXX",
        "purpose": "authentication",
        "verified_at": "2026-01-01T07:49:46+00:00"
    },
    "message": "OTP verified successfully",
    "meta": {
        "request_id": "8588ee1b-00b1-4756-b778-5607f6b3528d",
        "timestamp": "2026-01-01T07:49:46+00:00"
    }
}

🟠401UNAUTHORIZED

🟠403INSUFFICIENT_SCOPE

🟠422VALIDATION_ERROR

🟠422WHATSAPP_NOT_CONFIGURED

🟠429RATE_LIMIT_EXCEEDED

🔴500INTERNAL_ERROR

Verify an OTP code that was sent via the /auth/send-otp endpoint#

Required Scope#

Rate Limiting#

Verification Flow#

Error Scenarios#