Quick start

The 30-second version — install the SDK, drop it into a Playwright test, and you're done. No inbox provisioning, no regex parsing.

import { test, expect } from '@playwright/test';
import { SandboxClient } from '@otpmagiclink/playwright';

const sandbox = new SandboxClient({
  apiKey: process.env.OTP_API_KEY!,
});

test('signup with OTP', async ({ page }) => {
  await page.goto('/signup');
  await page.fill('[name=email]', 'test@yourapp.com');
  await page.click('button[type=submit]');

  const otp = await sandbox.waitForOtp('test@yourapp.com');

  await page.fill('[name=otp]', otp);
  await expect(page).toHaveURL('/dashboard');
});

You already write E2E tests. Add one line to grab the code your app just emailed.

Install SDK

The Playwright SDK is a standalone npm package with zero runtime dependencies. Cypress users can use the same client — theSandboxClient works in any Node context.

npm install --save-dev @otpmagiclink/playwright

pnpm add -D @otpmagiclink/playwright

yarn add -D @otpmagiclink/playwright

Get an API key from /dashboard and set OTP_API_KEY in your .env.test or CI secrets.

SDK reference

All methods return promises. Timeouts default to 10 seconds; adjust with { timeout: 30_000 }.

const otp = await sandbox.waitForOtp('user@example.com', {
  timeout: 15_000,
  pollInterval: 250,
});
await page.fill('[name=otp]', otp);

const link = await sandbox.waitForMagicLink('user@example.com');
await page.goto(link);
await expect(page).toHaveURL('/dashboard');

await sandbox.followMagicLink(page, 'user@example.com');

const messages = await sandbox.getInbox('user@example.com');
expect(messages[0].subject).toContain('Welcome');

test('magic link expires after 1 hour', async ({ page }) => {
  await sandbox.advanceClock(3_600);
  const link = await sandbox.waitForMagicLink('user@example.com');
  await page.goto(link);
  await expect(page.getByText('Link expired')).toBeVisible();
});

test.afterEach(async () => {
  await sandbox.resetClock();
});

Auth stack recipes

The pattern is always the same: point your auth library's delivery function at the sandbox in test mode, then use waitForOtp() in your tests.

import { betterAuth } from 'better-auth';
import { emailOTP } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    emailOTP({
      async sendVerificationOTP({ email, otp }) {
        if (process.env.NODE_ENV === 'test') {
          return fetch(`${process.env.OTP_SANDBOX_URL}/v1/verifications`, {
            method: 'POST',
            headers: {
              Authorization: `Bearer ${process.env.OTP_API_KEY}`,
              'Content-Type': 'application/json',
            },
            body: JSON.stringify({
              identifier: email,
              channel: 'EMAIL',
              kind: 'OTP',
            }),
          });
        }
        return resend.emails.send({
          from: 'auth@yourapp.com',
          to: email,
          subject: 'Your code',
          text: `Your code is ${otp}`,
        });
      },
    }),
  ],
});

test('clerk email OTP signup', async ({ page }) => {
  const email = 'test+clerk_test@yourapp.com';

  await page.goto('/sign-up');
  await page.fill('input[name=emailAddress]', email);
  await page.click('button[type=submit]');

  const otp = await sandbox.waitForOtp(email);

  await page.fill('input[name=code]', otp);
  await expect(page).toHaveURL('/dashboard');
});

import EmailProvider from 'next-auth/providers/email';

export const authOptions = {
  providers: [
    EmailProvider({
      server: process.env.EMAIL_SERVER,
      from: 'noreply@yourapp.com',
      async sendVerificationRequest({ identifier: email, url }) {
        if (process.env.NODE_ENV === 'test') {
          return fetch(`${process.env.OTP_SANDBOX_URL}/v1/verifications`, {
            method: 'POST',
            headers: {
              Authorization: `Bearer ${process.env.OTP_API_KEY}`,
              'Content-Type': 'application/json',
            },
            body: JSON.stringify({
              identifier: email,
              channel: 'EMAIL',
              kind: 'MAGIC_LINK',
              redirectUrl: url,
            }),
          });
        }
        // Normal production path
      },
    }),
  ],
};

REST API overview

The SDK is a thin wrapper over a small REST API. Use REST directly if you're testing from a non-Node language or need control the SDK doesn't expose. Base URL: https://your-domain.com/api/v1

1. Your app calls Create verification, or your auth library's test hook does.
2. The sandbox captures the OTP or magic link — no real email is sent.
3. Your test polls Sandbox inbox (or uses sandbox.waitForOtp()) to retrieve it.
4. Your test fills the OTP into your app's form, or navigates to the magic-link URL.

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"
}

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"
}

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

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'"]
    }
  }
}