Phone, email and identity checks

verify confirms a phone number or email address belongs to the person who gave it, and checks identity at the level a market requires. Reach for it at sign-up, before payouts or in regulated flows.

verify:
  driver: twilio-verify
  key: secret:VERIFY_KEY
  code: { ttl: 10m, tries: 5 }
  limits: { per-number: 3, per-ip: 10, window: 10m }
  email: { base: https://app.example.com, path: /verify/email }
  identity: { in: digilocker, eu: onfido }
  require: { in: substantial, eu: high }
  policy: privacy-2026-10
  drivers:
    twilio-verify: { account: secret:TWILIO_ACCOUNT_SID, token: secret:TWILIO_AUTH_TOKEN, service: VAxxxxxxxx }
    onfido: { token: secret:ONFIDO_TOKEN, workflow: wf_123, region: eu }

import { verify } from "mainsdk/verify";

const started = await verify.phone({ number: input.phone, for: user.id });
// later, with the code the person typed
const check = await verify.phone.check({ id: started.id, code: input.code });
if (check.ok) await db.users.for(user).update(user.id, { phone: check.number, phoneVerified: true });

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { verify } from "mainsdk/verify";

describe("verify", () => {
  it("verify AC1 checks a code once", async () => {
    const app = createTestApp({ yaml: "schema: 1\nverify:\n  driver: local\n" });
    const started = await verify.phone({ number: "+91 98765 43210" });
    const code = app.verifyKit().outbox.at(-1)?.code ?? "";
    assert.deepEqual(await verify.phone.check({ id: started.id, code }), { ok: true, number: "+919876543210" });
    assert.deepEqual(await verify.phone.check({ id: started.id, code }), { ok: false });
  });
});

verify:
  driver: twilio-verify

Quick start

verify:
  driver: local

"use server";
import { auth } from "mainsdk";
import { verify } from "mainsdk/verify";

declare function saveVerifiedPhone(user: string, number: string): Promise<void>;   // your own record

export async function sendCode(req: Request, phone: string) {
  const session = await auth.require(req);
  const started = await verify.phone({ number: phone, for: session.user, req });
  return started.id;   // { sent: true, id, expiresAt }; the person gets the code
}

export async function checkCode(req: Request, id: string, code: string) {
  const session = await auth.require(req);
  const check = await verify.phone.check({ id, code });
  if (check.ok) await saveVerifiedPhone(session.user, check.number);
  return check.ok;
}

verify.phone() normalises the number to E.164, makes a six-digit code and hands it to the driver. The code ends after 10 minutes or 5 wrong tries. verify.phone.check() answers { ok: true, number } once, and { ok: false } for every other case, so a wrong code, an expired one and an unknown id look the same.

Configuration

verify:
  driver: twilio-verify                   # twilio-verify | bird | local
  key: secret:VERIFY_KEY                  # keys the digest of codes, numbers and addresses
  code: { ttl: 10m, tries: 5 }            # a setting may only lower these
  limits: { per-number: 3, per-ip: 10, window: 10m }
  email: { base: https://app.example.com, path: /verify/email }
  identity: { in: digilocker, eu: onfido, default: persona }
  require: { in: substantial, eu: high }
  policy: privacy-2026-10
  drivers:
    twilio-verify: { account: secret:TWILIO_ACCOUNT_SID, token: secret:TWILIO_AUTH_TOKEN, service: VAxxxxxxxx }
    onfido: { token: secret:ONFIDO_TOKEN, workflow: wf_123, region: eu }

Phone sends sit behind the verify door of bot defence: with a bots section, a request the door challenges or denies, or a country the pumping check refuses, stops before a message is paid for.

Building it by hand

The SDK builds verify for you from main.yaml. Call these only when you wire it by hand, for example in a test.

What you get

verify sits next to auth: auth signs people in, verify confirms facts about them. One call each for a phone, an email and an identity, the same on every driver. MainSDK makes and judges the code itself, so switching provider changes no answer. Every answer is the same shape and takes at least 400 ms, so neither tells an attacker which numbers or addresses have an account.

Examples

Confirm an email address

verify.email() sends a link, not a code, through your email and minted by share, so it is a getqr.id link that expires and can be revoked. The link lands on email.base plus email.path with a token; your route confirms it. Confirm on a POST, so a mail scanner that opens the link does not spend it.

import { verify } from "mainsdk/verify";

export async function POST(req: Request) {
  const { token } = (await req.json()) as { token: string };
  const check = await verify.email.confirm(token);
  return Response.json({ confirmed: check.ok });   // check.address is the confirmed address
}

export async function sendLink(address: string) {
  return verify.email({ address });   // { sent: true, id, expiresAt }
}

Check identity at the market's level

verify.identity() takes the level, the market, the claims you ask for, your purpose, the person and their consent. The market picks the driver from identity, and require can raise the level. It sends the person to the provider and returns where; complete reads the outcome.

import { verify } from "mainsdk/verify";

export async function startAgeCheck(user: string, market: string) {
  const started = await verify.identity({
    level: "substantial",
    market,
    claims: ["age_over_18"],
    purpose: "Sell age-restricted items",
    user,
    consent: { policy: "privacy-2026-10" },
  });
  return started.url;   // send the person here; keep started.id
}

export async function finishAgeCheck(id: string, code?: string) {
  const done = await verify.identity.complete(code ? { id, code } : { id });
  return done.status === "approved" ? done.claims : null;   // { age_over_18: true }
}

Only the claims you ask for are kept, each labelled, with a consent record of the time, the purpose and the policy. Ask for age_over_18 rather than a birth date: a claim that identifies a person (a birth date, a name, a document number) that you don't list in need fails with MAIN-IDENT-0001. A level the market's driver cannot reach fails with MAIN-VERIFY-0004 before the person is sent anywhere.

Errors and checks

See check codes and errors.

Swapping drivers

Change one line; your verify.* calls stay the same.

verify:
  driver: bird   # was twilio-verify
  drivers:
    bird: { workspace: ws_123, channel: ch_123, key: secret:BIRD_ACCESS_KEY }

See Swap a driver. Code, expiry and tries live in MainSDK, so pending checks keep working across a swap.

Testing

createTestApp runs verify on the local driver: the codes stay in an outbox, nothing leaves the app.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { verify } from "mainsdk/verify";

describe("verify", () => {
  it("verify AC1 checks a code once", async () => {
    const app = createTestApp({ yaml: "schema: 1\nverify:\n  driver: local\n" });
    const started = await verify.phone({ number: "+91 98765 43210" });
    const code = app.verifyKit().outbox.at(-1)?.code ?? "";
    assert.deepEqual(await verify.phone.check({ id: started.id, code }), { ok: true, number: "+919876543210" });
    assert.deepEqual(await verify.phone.check({ id: started.id, code }), { ok: false });
  });
});

runVerifyConformance from @mainsdk/testing checks a phone driver against the spec: the code, number and channel it sends, how it reads a 5xx, a 429 and a rejected recipient, and that a swap of driver changes no answer.

Security and privacy

• Phone numbers and email addresses are personal data. The record that holds a number carries the label personal, lives no longer than the code and is deleted when the check succeeds. A code is kept only as a keyed digest, a link token only as a SHA-256 digest.
• Every send and check is audited with the number masked and never in the clear; an address never appears in a log or audit record.
• Ask only for what you need. Identity claims you do not ask for are dropped before your app sees them, and the check is spent once, so a repeat stores nothing twice.
• verify calls the provider only when a person asks; a provider outage fails that one send, never the app (ADR-0003). It is free and runs in your app.

FAQ

Is this the same as WhatsApp sign-in? No. WhatsApp one-time codes for sign-in belong to auth. verify confirms a number or address that a signed-in person gives you.

Does a failed delivery tell the caller the number is bad? Only when the failure says nothing about the recipient, such as an outage. A provider that refuses one recipient leaves the answer the same and the refusal is logged without the recipient.

Do I need a migration to change provider? No. Phone and email checks are short-lived and MainSDK holds their state. Identity results you keep live in your own db.

Next

• Sign-in and sessions
• Data and records
• Privacy and data rights