Two-factor codes (TOTP)

Testing a login that requires a time-based one-time code usually means either disabling two-factor in test environments or scraping a phone. mailcatchr stores the authenticator instead and hands your test the current code.

Registering an authenticator

Open Tools → Authenticators → New authenticator and paste the secret the application shows when enabling two-factor (the text under the QR code, usually base32). Give it a name. The workspace now owns an authenticator that produces the same codes a phone app would.

Fetching a code

GET /v1/totp/{totpId}/code

{ "code": "482910", "expiresAt": "2026-09-20T09:41:30+00:00", "expiresInSeconds": 18 }

If expiresInSeconds is small, the next code may be what the application expects by the time your form submits. Waiting it out is simpler than handling the edge: sleep for expiresInSeconds + 1 and fetch again.

TypeScript

const totp = await mc.totps.code(authenticatorId);
await page.fill('input[name="otp"]', totp.code);

curl

curl -H "Authorization: Bearer $MAILCATCHR_API_KEY" \
  "https://api.mailcatchr.com/v1/totp/$TOTP_ID/code"

Scope

The key must include the authenticator in its authenticator scope. A key that does not gets 404. See API keys and scopes.

Limits

Plan	Authenticators
Free	1
Business	50