Optora API v2

A lightweight, production-ready OTP email verification API. Send one-time codes or magic links, verify them in one step, and get notified via webhooks — all over a simple REST interface.

How it works

Authentication

Optora is a self-hosted API — no API keys or tokens are required on requests. Secure it at the network or proxy level (firewall, reverse proxy, allowlist) for production use.

Base URL

All endpoints are relative to your deployment URL. The panel below shows your current deployment's base URL, detected automatically.

API Playground

Test all endpoints live from your browser. Requests go directly to this deployment — real emails will be sent.

Send Verification Code

Generates a one-time code and emails it to the user. Use the returned requestId to check verification status later.

curl -X POST https://your-app.vercel.app/api/otp/generate \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "organization": "Acme Inc",
    "type": "numeric",
    "subject": "Your verification code"
  }'

{
  "message": "Verification code sent to your email",
  "mode": "code",
  "requestId": "b7e3a2f1c4d8e9a0b1c2d3e4",
  "validityMinutes": 5
}

Send Magic Link

Emails a one-click verification link. When clicked, the link verifies the token server-side and optionally fires a webhook to your backend.

curl -X POST https://your-app.vercel.app/api/otp/send-link \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "organization": "Acme Inc",
    "webhookUrl": "https://your-server.com/hooks/verified"
  }'

{
  "message": "Verification link sent to your email",
  "mode": "link",
  "requestId": "c9f4b3e2d5a6b7c8d9e0f1a2",
  "validityMinutes": 5,
  "webhookRegistered": true
}

Verify Code

Validates an OTP submitted by the user. Returns success if the code matches and has not expired.

curl -X POST https://your-app.vercel.app/api/otp/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "otp": "482910"}'

Verify Magic Link

This endpoint is called automatically when the user clicks the link in their email. You do not need to call it from your backend.

Check Status

Poll the verification status of a request by its ID. Useful as a reliable fallback when webhooks are not available.

{
  "requestId": "b7e3a2f1c4d8e9a0",
  "email": "user@example.com",
  "verified": true,
  "verifiedAt": "2026-05-28T10:30:00.000Z",
  "expiresAt": "2026-05-28T10:35:00.000Z"
}

Rate Limiting

Requests are rate-limited per IP and email address. Configure thresholds with environment variables.

Webhooks

Optora can notify your server when a magic-link verification completes. Pass webhookUrl in the /otp/send-link request.

Payload delivered to your server

{
  "event": "email.verified",
  "email": "user@example.com",
  "requestId": "b7e3a2f1...",
  "verifiedAt": "2026-05-28T10:30:00.000Z"
}

• Fire-and-forget — the confirmation page does not wait for your server to respond
• 5-second timeout. Slow or unreachable URLs are aborted and logged server-side
• Only http:// and https:// URLs are accepted
• No automatic retries — use GET /api/otp/status/:requestId as a reliable fallback

Environment Variables

All variables live in sample.env. Copy it to .env for local development. For Vercel, add them under Settings → Environment Variables.

Error Reference

All errors return { "error": "message" }.