One Time Codes

Passlock can issue mailbox challenges for email-based one-time code flows. They work well for account signup, passwordless login, and account management scenarios such as email-change verification.

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

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 - 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
• Reference - detailed @passlock/server function reference
• REST API mailbox challenges - raw HTTP requests and response shapes