Reference

This page covers the public @passlock/server helpers for mailbox challenges in more detail.

Shared request fields

All mailbox challenge helpers take shared Passlock config as their second argument:

• tenancyId - your Passlock tenancy ID
• apiKey - your tenancy API key
• endpoint - optional API base URL override, defaults to https://api.passlock.dev

Mailbox challenges also share a few important concepts:

• purpose is an application-defined string. Passlock validates it as a 1-64 character string using only A-Z, a-z, 0-9, ., _, :, and -.
• metadata must be JSON-compatible.
• challengeId identifies the challenge.
• secret is stored by your app and sent back during verification.
• code is the one-time code you deliver to the user.

Tip

Use Passlock from @passlock/server for a configured safe class client, or Passlock from @passlock/server/unsafe for a configured throwing passlock. Standalone safe functions are available from @passlock/server; throwing functions are available from @passlock/server/unsafe.

createMailboxChallenge

Use createMailboxChallenge to start a flow and obtain the generated challengeId, secret, code, and rendered message content (html and text).

Default (safe)

import { Passlock } from "@passlock/server";

const passlock = new Passlock({ tenancyId: "myTenancyId", apiKey: "myApiKey" });

const result = await passlock.createMailboxChallenge({
  email: "jdoe@example.com",
  purpose: "signup",
  userId: "123",
  metadata: {
    signupId: "signup_123",
  },
  invalidateOthers: true,
});

if (result.success) {
  console.log(result.value.challenge.challengeId);
  console.log(result.value.challenge.message.text);
} else {
  console.error(result.error.message);
}

Unsafe

import { Passlock } from "@passlock/server/unsafe";

const passlock = new Passlock({ tenancyId: "myTenancyId", apiKey: "myApiKey" });

const result = await passlock.createMailboxChallenge({
  email: "jdoe@example.com",
  purpose: "signup",
  userId: "123",
  metadata: {
    signupId: "signup_123",
  },
  invalidateOthers: true,
});

console.log(result.challenge.challengeId);
console.log(result.challenge.secret);
console.log(result.challenge.code);
console.log(result.challenge.message.html);

Functions (safe)

import { createMailboxChallenge } from "@passlock/server";

const result = await createMailboxChallenge({
  email: "jdoe@example.com",
  purpose: "signup",
  invalidateOthers: true,
}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

if (result.success) {
  console.log(result.value.challenge.challengeId);
  console.log(result.value.challenge.message.text);
} else {
  console.error(result.error.message);
}

Functions (unsafe)

import { createMailboxChallenge } from "@passlock/server/unsafe";

const result = await createMailboxChallenge({
  email: "jdoe@example.com",
  purpose: "signup",
  userId: "123",
  metadata: {
    signupId: "signup_123",
  },
  invalidateOthers: true,
}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

console.log(result.challenge.challengeId);
console.log(result.challenge.secret);
console.log(result.challenge.code);
console.log(result.challenge.message.html);

Choose your code style

Important create options

• invalidateOthers deletes other pending challenges with the same purpose and subject.
• When userId is present, Passlock scopes invalidation by userId; otherwise it scopes by email.
• skipRateLimit bypasses mailbox challenge rate limiting and is usually best left unset.

Create errors

• @error/ChallengeRateLimited
• @error/Forbidden

getMailboxChallenge

Use getMailboxChallenge to read a pending challenge without exposing the secret or code. This is useful when you need to restore an in-progress flow or show which mailbox is being verified.

Default (safe)

import { Passlock } from "@passlock/server";

const passlock = new Passlock({ tenancyId: "myTenancyId", apiKey: "myApiKey" });

const result = await passlock.getMailboxChallenge({
  challengeId: "challenge_123",
});

if (result.success) {
  console.log(result.value._tag); // "Challenge"
  console.log(result.value.email);
  console.log(result.value.metadata);
} else {
  console.error(result.error.message);
}

Unsafe

import { Passlock } from "@passlock/server/unsafe";

const passlock = new Passlock({ tenancyId: "myTenancyId", apiKey: "myApiKey" });

const challenge = await passlock.getMailboxChallenge({
  challengeId: "challenge_123",
});

console.log(challenge._tag); // "Challenge"
console.log(challenge.email);
console.log(challenge.metadata);

Functions (safe)

import { getMailboxChallenge } from "@passlock/server";

const result = await getMailboxChallenge({
  challengeId: "challenge_123",
}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

if (result.success) {
  console.log(result.value._tag); // "Challenge"
  console.log(result.value.email);
  console.log(result.value.metadata);
} else {
  console.error(result.error.message);
}

Functions (unsafe)

import { getMailboxChallenge } from "@passlock/server/unsafe";

const challenge = await getMailboxChallenge({
  challengeId: "challenge_123",
}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

console.log(challenge._tag); // "Challenge"
console.log(challenge.email);
console.log(challenge.metadata);

Choose your code style

Get errors

• @error/NotFound
• @error/Forbidden

verifyMailboxChallenge

Use verifyMailboxChallenge to check the code against the stored challenge. Pass challengeId, secret, and the user-supplied code.

Default (safe)

import { Passlock } from "@passlock/server";

const passlock = new Passlock({ tenancyId: "myTenancyId", apiKey: "myApiKey" });

const result = await passlock.verifyMailboxChallenge({
  challengeId: "challenge_123",
  secret: "abc123def-ghi456jkl-mno789pqr",
  code: "123456",
});

if (result.success) {
  console.log(result.value.challenge.email);
} else {
  console.error(result.error.message);
}

Unsafe

import { Passlock } from "@passlock/server/unsafe";

const passlock = new Passlock({ tenancyId: "myTenancyId", apiKey: "myApiKey" });

const result = await passlock.verifyMailboxChallenge({
  challengeId: "challenge_123",
  secret: "abc123def-ghi456jkl-mno789pqr",
  code: "123456",
});

console.log(result.challenge._tag); // "Challenge"
console.log(result.challenge.purpose);
console.log(result.challenge.email);

Functions (safe)

import { verifyMailboxChallenge } from "@passlock/server";

const result = await verifyMailboxChallenge({
  challengeId: "challenge_123",
  secret: "abc123def-ghi456jkl-mno789pqr",
  code: "123456",
}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

if (result.success) {
  console.log(result.value.challenge.email);
} else {
  console.error(result.error.message);
}

Functions (unsafe)

import { verifyMailboxChallenge } from "@passlock/server/unsafe";

const result = await verifyMailboxChallenge({
  challengeId: "challenge_123",
  secret: "abc123def-ghi456jkl-mno789pqr",
  code: "123456",
}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

console.log(result.challenge._tag); // "Challenge"
console.log(result.challenge.purpose);
console.log(result.challenge.email);

Choose your code style

Successful verification returns ChallengeVerified with a readable nested challenge. The response excludes the secret and one-time code, so your app should keep validating the returned purpose, email, and userId against local expectations.

Verify errors

• @error/InvalidChallenge
• @error/InvalidChallengeCode
• @error/ChallengeExpired
• @error/ChallengeAttemptsExceeded
• @error/Forbidden

deleteMailboxChallenge

Use deleteMailboxChallenge when a user cancels a flow or when you want to clear pending challenge state explicitly.

Default (safe)

import { Passlock } from "@passlock/server";

const passlock = new Passlock({ tenancyId: "myTenancyId", apiKey: "myApiKey" });

const result = await passlock.deleteMailboxChallenge({
  challengeId: "challenge_123",
});

if (result.success) {
  console.log(result.value._tag); // "ChallengeDeleted"
} else {
  console.error(result.error.message);
}

Unsafe

import { Passlock } from "@passlock/server/unsafe";

const passlock = new Passlock({ tenancyId: "myTenancyId", apiKey: "myApiKey" });

const result = await passlock.deleteMailboxChallenge({
  challengeId: "challenge_123",
});

console.log(result._tag); // "ChallengeDeleted"

Functions (safe)

import { deleteMailboxChallenge } from "@passlock/server";

const result = await deleteMailboxChallenge({
  challengeId: "challenge_123",
}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

if (result.success) {
  console.log(result.value._tag); // "ChallengeDeleted"
} else {
  console.error(result.error.message);
}

Functions (unsafe)

import { deleteMailboxChallenge } from "@passlock/server/unsafe";

const result = await deleteMailboxChallenge({
  challengeId: "challenge_123",
}, { tenancyId: "myTenancyId", apiKey: "myApiKey" });

console.log(result._tag); // "ChallengeDeleted"

Choose your code style

deleteMailboxChallenge resolves to { _tag: "ChallengeDeleted" }.

Delete errors

• @error/Forbidden

If you are not using Node.js, the same behavior is documented in the REST API mailbox challenge reference.