Mailbox challenges / one time authentication codes

Passlock can issue mailbox challenges for email-based one-time code flows. They work well for email verification, account management and account recovery scenarios. They can also be used for passwordless login if passkeys are not available/supported.

Server-side API

Mailbox challenges are a server-side feature, requiring authentication via your API key.

Each challenge has three important values:

• challengeId identifies the challenge
• secret is kept by your app and submitted during verification
• code is the one-time code delivered to the user by email

Treat the code and secret separately

The emailed code is only one part of the verification step. Your app must also present the stored secret, so do not rely on the emailed code alone.

How it works

High level overview of the mailbox challenge flow.

Note

This simplified flow does not include rate limiting, expiry, invalidation etc. (see below)

sequenceDiagram
  Actor User as 
  participant Backend
  participant Server as @passlock/server

  User->>Backend: signup
  Backend->>Server: createMailboxChallenge(sendEmail: true)
  Server-)User: email code to user
  Server-->>Backend: code, secret
  Backend->>Backend: save secret in session
  User->>Backend: enter code
  Backend->>Backend: lookup session secret
  Backend->>Server: verify challenge (id, code, secret)

1. Your backend calls createMailboxChallenge with an email address, a purpose such as signup, login, or email-change, and sendEmail: true
2. Passlock creates the challenge, sends the email, and returns challengeId, secret, code, and a rendered message with html and text content
3. Your backend stores challengeId and secret in an HTTP-only cookie or server-side session
4. The user enters the code
5. Your backend calls verifyMailboxChallenge with challengeId, secret, and code
6. Passlock returns a response indicating if the challenge response is authentic

More than a random code

It can be tempting to think “I’ll just generate a 6-digit code myself”, but a production-ready flow needs more than that. You need an app-held secret to reduce man-in-the-middle risk, challenge expiry, invalidation of older outstanding codes, and consistent verification rules.

Passlock handles those moving parts for you so you can focus on your signup, login, and account-management logic.

Want to send the emails yourself?

Mailbox challenge creation still returns the raw code and a rendered message with html and text content. If you omit sendEmail, or pass sendEmail: false, Passlock creates the challenge without sending email.

You can send the rendered email through your own infrastructure, or use the raw code to render a completely custom template.

Next steps

• Mailbox verification - verify mailbox ownership before creating or activating an account
• Passwordless logins - authenticate a user with an emailed one-time code
• Account management - verify a new mailbox before updating account details
• Account recovery - recover access when the user can no longer use their passkeys
• Reference - detailed @passlock/server function reference
• REST API mailbox challenges - raw HTTP requests and response shapes