Optora API

Overview

Optora provides two verification flows. Choose the one that fits your product:

Authentication

Optora uses no API keys by default — it is designed to run as your own private backend. Protect your endpoints with your own authentication layer (middleware, API gateway, etc.) before deploying publicly.

Quick Start

Base URL — detected automatically from the request host. Override with DOCS_API_URL:

https://your-app.vercel.app

Send a verification code:

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

Generate OTP

Generates a one-time code and emails it to the user. If an unexpired, unverified OTP exists for the email, it is reused (up to 3 attempts).

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

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

Send Magic Link

Emails a one-click verification link. When the user clicks the link, their browser opens a confirmation page and — if configured — your server receives a webhook.

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

Called automatically when the user clicks the link in their email. Returns an HTML confirmation page — you do not need to call this from your backend.

Check Status

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

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

Rate Limiting

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

Webhooks

Optora notifies 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-31T10: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

Copy sample.env to .env for local development. For Vercel, add them under Settings → Environment Variables.

Error Reference

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