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 you deliver 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 WebApp
  participant Server as @passlock/server

  User->>WebApp: signup
  WebApp->>Server: create challenge
  Server-->>WebApp: code, secret
  WebApp->>WebApp: save secret in session
  WebApp-)User: email code to user
  User->>WebApp: enter code
  WebApp->>WebApp: lookup session secret
  WebApp->>Server: verify challenge (code, secret)

1. Your app calls createMailboxChallenge with an email address and a purpose such as signup, login, or email-change.
2. Passlock returns a challenge containing challengeId, secret, code, and a rendered message with html and text content.
3. Your app stores challengeId and secret in an HTTP-only cookie or server-side session, then emails the code to the user. Send the rendered message content, or use the raw code to generate your own message.
4. The user enters the code into your app.
5. Your app calls verifyMailboxChallenge with challengeId, secret, and code.
6. Passlock returns a readable challenge payload that excludes the secret and code. Your app should still validate the challenge purpose and any expected local user before completing the flow.

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.

Why doesn’t Passlock email the codes?

Passlock does everything apart from actually sending the email. There are a few reasons for this:

1. The email should come from your domain - users should immediately recognise the sender. Security emails sent “on behalf of” are a red flag.
2. No need for SPF, DMARC and DKIM changes - if we were to send from your domain you’d need to setup these properties for our servers.
3. Flexibility - we return HTML and plain text message content. It’s responsive, supports dark mode and is tested in major email clients. We think it’s great, but you might disagree so we give you the flexibility to generate and send your own message content.

Next steps

• [Email verification][signup] - 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