Overview

otpmagiclink issues one-time passwords and magic links on behalf of your project. You never store raw tokens — we handle delivery, expiry, rate limiting, and audit logging.

1. Your backend calls Create verification.
2. We deliver the OTP or magic link (or capture it in sandbox).
3. The user enters the code or clicks the link.
4. Your backend calls Check OTP, or the magic link verifies automatically.

Postman / OpenAPI

Download the API spec and import it into Postman, Insomnia, or any OpenAPI-compatible client. The Postman collection includes collection variables and test scripts that chain verificationId and otpToken across requests.

API Simulator

Pick a project and API key, edit the sample payload, and send live requests against /api/v1. Sandbox projects are recommended for testing — no real email or SMS is sent.

Authentication

Send your project API key on every request:

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxx

Keys use the sk_ prefix. Sandbox project keys never send real email or SMS.

Create verification

{
  "identifier": "user@example.com",
  "channel": "EMAIL",
  "kind": "OTP"
}

{
  "identifier": "user@example.com",
  "channel": "EMAIL",
  "kind": "MAGIC_LINK",
  "redirectUrl": "https://yourapp.com/dashboard"
}

{
  "identifier": "+15551234567",
  "channel": "SMS",
  "kind": "OTP"
}

{
  "id": "cmqz5di97000qq48tkwksjltp",
  "status": "PENDING",
  "channel": "EMAIL",
  "kind": "MAGIC_LINK",
  "expiresAt": "2026-06-29T12:01:14.740Z"
}

{
  "id": "cmqz5di97000qq48tkwksjltp",
  "status": "PENDING",
  "channel": "EMAIL",
  "kind": "MAGIC_LINK",
  "expiresAt": "2026-06-29T12:01:14.740Z",
  "sandbox": {
    "message": "No real email is sent in sandbox. Use the sandbox inbox or GET /api/v1/sandbox/inbox/{identifier}/latest-link to retrieve the magic link or OTP."
  }
}

{
  "error": "Message delivery failed. Check your delivery config.",
  "detail": "Resend delivery failed: Domain not verified"
}

Check OTP

{
  "token": "482910"
}

{
  "id": "cmqz5di97000qq48tkwksjltp",
  "status": "VERIFIED",
  "verifiedAt": "2026-06-29T12:05:00.000Z",
  "redirectUrl": "https://yourapp.com/dashboard"
}

{
  "error": "Invalid token",
  "attemptsRemaining": 2
}

{
  "error": "Verification has expired"
}

Magic links

Magic links verify automatically when the user clicks the link in their email. You do not call this endpoint yourself.

On failure the user is redirected to /verify/error?reason=expired|invalid|not_found.

Sandbox

Sandbox projects capture messages instead of sending real email or SMS. Read them in the dashboard inbox or via API.

{
  "messages": [
    {
      "id": "msg_01jxxx",
      "identifier": "user@example.com",
      "subject": "Your verification code is 482910",
      "otp": "482910",
      "magicLink": null,
      "createdAt": "2026-06-29T12:00:00.000Z"
    },
    {
      "id": "msg_01jyyy",
      "identifier": "user@example.com",
      "subject": "Your sign-in link",
      "otp": null,
      "magicLink": "https://your-domain.com/api/v1/verify/magic?token=...&id=...",
      "createdAt": "2026-06-29T11:58:00.000Z"
    }
  ]
}

{
  "id": "msg_01jyyy",
  "identifier": "user@example.com",
  "magicLink": "https://your-domain.com/api/v1/verify/magic?token=...&id=...",
  "otp": null,
  "createdAt": "2026-06-29T11:58:00.000Z"
}

{
  "error": "No magic link found for this identifier"
}

Webhooks

Configure webhook URLs in the dashboard. Each POST is signed with X-Webhook-Signature (HMAC-SHA256(secret, "{timestamp}.{body}")).

Events

• verification.created — right after POST /verifications succeeds
• verification.verified — user completed verification (OTP check or magic link click)

{
  "id": "wh_evt_abc123",
  "event": "verification.created",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "environment": "production",
  "project": {
    "id": "cmqz44lie0009q48t1mtk2wv7",
    "name": "My App",
    "slug": "my-app"
  },
  "apiKey": {
    "id": "key_01jxxx",
    "name": "Production server"
  },
  "source": "api",
  "data": {
    "id": "cmqz5di97000qq48tkwksjltp",
    "projectId": "cmqz44lie0009q48t1mtk2wv7",
    "identifier": "user@example.com",
    "channel": "EMAIL",
    "kind": "MAGIC_LINK",
    "status": "PENDING",
    "expiresAt": "2026-06-29T12:10:00.000Z"
  }
}

{
  "id": "wh_evt_def456",
  "event": "verification.verified",
  "timestamp": "2026-06-29T12:05:00.000Z",
  "environment": "sandbox",
  "project": {
    "id": "cmqz25yvw0000x48txt367rpc",
    "name": "Sandbox",
    "slug": "sandbox"
  },
  "apiKey": {
    "id": "key_01jyyy",
    "name": "Dev key"
  },
  "source": "otp_check",
  "data": {
    "id": "cmqz5di97000qq48tkwksjltp",
    "projectId": "cmqz25yvw0000x48txt367rpc",
    "identifier": "user@example.com",
    "kind": "OTP",
    "channel": "EMAIL",
    "verifiedAt": "2026-06-29T12:05:00.000Z"
  }
}

{
  "id": "wh_evt_ghi789",
  "event": "verification.verified",
  "timestamp": "2026-06-29T12:05:00.000Z",
  "environment": "production",
  "project": {
    "id": "cmqz44lie0009q48t1mtk2wv7",
    "name": "My App",
    "slug": "my-app"
  },
  "apiKey": null,
  "source": "magic_link",
  "data": {
    "id": "cmqz5di97000qq48tkwksjltp",
    "projectId": "cmqz44lie0009q48t1mtk2wv7",
    "identifier": "user@example.com",
    "kind": "MAGIC_LINK",
    "channel": "EMAIL",
    "verifiedAt": "2026-06-29T12:05:00.000Z"
  }
}

Monitoring & smoke tests

Use layered checks to catch API issues early — from lightweight uptime probes to full end-to-end verification flows.

BASE_URL=https://your-app.run.app API_KEY=sk_sandbox_key yarn smoke

curl -X POST https://your-app.run.app/api/cron/smoke \
  -H "Authorization: Bearer $CRON_SECRET"

CI runs Playwright API tests before deploy, then yarn smoke after deploy. If smoke fails, the GitHub Actions workflow fails (staging on main, dev on develop). Required secrets: K6_STAGING_API_KEY / K6_DEV_API_KEY (sandbox sk_… keys).

Errors

Errors return JSON with an error string and optional detail or details.

{
  "error": "Invalid request body",
  "details": {
    "fieldErrors": {
      "channel": ["Invalid enum value. Expected 'EMAIL' | 'SMS'"]
    }
  }
}