Skip to Content
better-auth-plugins

Waitlist

Gate sign-up behind a waitlist with double opt-in, admin approval, and invite codes.

The waitlist plugin lets people join a waitlist with their email while sign-up is closed. They confirm their email (double opt-in), admins approve entries, each approval sends an invite, and only approved emails can create an account.

  • Gates every way a user is created, not only email sign-up: OAuth, magic link, email OTP, and users created by your own server code.
  • Double opt-in by default: nobody can put someone else's email on the waitlist.
  • Answers the join request the same way for new, waiting, and existing emails, so the waitlist can't be used to find out who signed up.
  • Single-use invite codes, bound to one email, that expire.
  • Status and "leave the waitlist" links for every entry.

Installation

Install the package

npm install @checodo/better-auth-waitlist

Add the plugin to your auth config

The plugin hands you the tokens and codes; you send the emails and build the links to pages of your app (see Pages to build).

auth.ts
import { betterAuth } from "better-auth";
import { waitlist } from "@checodo/better-auth-waitlist";

export const auth = betterAuth({
  plugins: [
    waitlist({
      sendConfirmationEmail: async ({ email, token }) => {
        await sendEmail({
          to: email,
          subject: "Confirm your spot on the waitlist",
          text: `https://example.com/waitlist/confirm?token=${token}`,
        });
      },
      sendInvite: async ({ email, inviteCode }) => {
        await sendEmail({
          to: email,
          subject: "You're in!",
          text: `https://example.com/sign-up?invite=${inviteCode}`,
        });
      },
    }),
  ],
});

Migrate the database

The plugin adds a waitlistEntry table (see Schema).

npx auth@latest migrate

Add the client plugin

auth-client.ts
import { createAuthClient } from "better-auth/client";
import { waitlistClient } from "@checodo/better-auth-waitlist/client";

export const authClient = createAuthClient({
  plugins: [waitlistClient()],
});

Usage

Join the waitlist

const { data, error } = await authClient.waitlist.join({
  email: "ada@example.com",
  metadata: { source: "launch-tweet" }, // optional, stored as JSON
});
// data: { success: true }

The answer is { success: true } whether the email is new, already on the waitlist, or already has an account. With advanced.backgroundTasks configured, the plugin's callbacks (sendConfirmationEmail, onJoin, sendInvite) run after the response, so its timing doesn't give anything away either.

Double opt-in

By default (confirmEmail: true), a new entry is unconfirmed and sendConfirmationEmail gets a token for the confirmation link. The entry only counts once the link is opened: only confirmed entries can be approved, and onJoin and autoApprove run after the confirmation.

  • The link works for confirmationExpiresIn (2 days by default). Joining again with an unconfirmed email sends the link again, valid for another confirmationExpiresIn, for people who lost the first email.
  • Whoever fills in the join form doesn't have to own the address, so resends are limited: at most one every 5 minutes, and 3 in total. An address gets at most 4 confirmation emails until its entry expires, however often someone submits it, also when the requests arrive at the same time: the link is renewed in a single conditional write, so only one of them sends an email. The answer to the join request is the same whether an email went out or not.
  • Opening the link several times, also at the same time, confirms the entry once: onJoin and autoApprove run once.
  • The entry's confirmedAt records when the link was opened. It stays null when nobody confirmed the email: without double opt-in, for emails an admin invited directly before they confirmed, and for entries confirmed before the field existed. With the audit log, the confirmation is also recorded there as waitlist.confirmed.
  • Unconfirmed entries whose link has expired are deleted, so emails nobody confirmed aren't kept (see Privacy).
  • An admin can still invite an unconfirmed email directly (see Managing the waitlist), for example someone who asked in person. That is the admin's call.

Without double opt-in (confirmEmail: false), new entries are pending right away and sendConfirmationEmail isn't needed.

Pages to build

The emails link to pages of your app, which call the plugin with the token from the URL:

// /waitlist/confirm?token=...  (from sendConfirmationEmail)
await authClient.waitlist.confirm({ token });

// /waitlist/status?token=...  (link it in any email that carries a token)
const { data } = await authClient.waitlist.getStatus({ query: { token } });
// data: { email, status, position, inviteExpiresAt }
// position: 1-based place among pending entries, null otherwise

// /waitlist/leave?token=...
await authClient.waitlist.leave({ token });

// /sign-up?invite=...  (from sendInvite): show the form only for valid codes
const { data: invite } = await authClient.waitlist.checkInvite({ query: { code } });
// invite: { valid: boolean }

Confirming happens in a request your page makes, not when the email link is opened, so link scanners in mail programs don't confirm entries by accident. sendInvite also gets the entry's token, to put status and leave links in the invite email.

There's no way to look an entry up by email: only someone with the token, which is only ever sent to that email, can see its status or remove it. The admin endpoints don't return tokens either. Invalid or unknown tokens get INVALID_TOKEN.

Tokens and invite codes are stored as SHA-256 hashes (tokenHash, inviteCodeHash), like passwords: someone who can read your database (a backup, a leaked replica) can't use them. The plain values only exist in the emails, in onJoin, and in the admin response that issues an invite. So the plugin can't send the same token twice: a confirmation resend and an admin approval each come with a new token, and links from earlier emails stop working. The newest email always has working links.

Treat tokens like passwords anyway: anyone with a link (a forwarded email, say) can see the entry's status and remove it, so don't log them.

How an entry moves

StatusMeaning
unconfirmedJoined, but hasn't confirmed the email yet
pendingOn the waitlist, waiting for approval
approvedMay create an account until the invite expires
rejectedMay not create an account
registeredCreated an account; the invite can't be used again

Approving an entry creates an invite code, sets its expiry (inviteExpiresIn, 7 days by default), and calls sendInvite.

Sign-up

While the plugin is enabled, a user can only be created for an approved email whose invite hasn't expired. Everyone else gets a 403:

{ "code": "EMAIL_NOT_APPROVED", "message": "This email has not been approved to sign up yet" }

The check runs whenever a user is created, so it covers every sign-up method: email and password, OAuth, magic link, email OTP, phone number, and Sign-In with Ethereum. Existing users keep signing in as usual. That includes users your own server code creates directly, outside a request, for example a seed script: they are blocked too, unless their email is in allow or bypass lets them through. Some ways in skip the waitlist:

  • allow: emails ("ceo@acme.com") and domains ("acme.com", including subdomains) that may always sign up.
  • bypass: a function that gets the request creating the user (null outside a request). By default, users created by admins through the admin plugin's createUser skip the waitlist.

Users without a real email are blocked too, because their generated email is never on the waitlist:

Sign-in methodGenerated email
Anonymous gueststemp-...@<emailDomainName>
Phone number sign-up on verificationwhat signUpOnVerification.getTempEmail returns
Sign-In with Ethereum without an email<wallet address>@<emailDomainName>
Steam, Epic Games, and Xbox (authentication)<account id>@steam.invalid, epic.invalid, xbox.invalid

To keep such a method open, put its domain in allow, or let its requests through with bypass:

auth.ts
waitlist({
  // phone number and gaming sign-ups skip the waitlist
  allow: ["phone.example.com", "steam.invalid", "epic.invalid", "xbox.invalid"],
  // and so do guests (keep admins' createUser, the default)
  bypass: (context) =>
    context?.path === "/admin/create-user" || context?.path === "/sign-in/anonymous",
});

Allowed domains need email verification

An allow entry lets anyone sign up with an email on that domain, whether or not they own the address. Without better-auth's requireEmailVerification, someone could sign up as anything@your-company.com and get in. Allowed domains are only as safe as your email verification.

Invite codes

The approved email alone is enough by default

With the default requireInviteCode: false, anyone who signs up with an approved email gets in, whether or not they got the invite. To make sure only the invited person can claim the account, turn on requireInviteCode, or better-auth's requireEmailVerification so the account can't be used without access to the inbox. Social sign-in is only as safe as the provider's email: Google and GitHub return addresses they have verified, but some providers can return an address nobody verified (multi-tenant Microsoft Entra ID, custom OAuth or OIDC providers). Use requireInviteCode with those.

With requireInviteCode: true, the invite code has to come with the sign-up. Without a code, every sign-up fails with INVITE_CODE_REQUIRED; with a code that doesn't belong to an approved entry for that email, with INVALID_INVITE_CODE. Both answers are the same whether the email is approved or not, so sign-up attempts don't reveal who is on the waitlist. Codes are compared in constant time.

// email and password
await authClient.signUp.email(
  { email, password, name },
  { headers: { "x-invite-code": inviteCode } },
);

// social sign-in
await authClient.signIn.social({
  provider: "github",
  additionalData: { inviteCode },
});

// any other method: the x-invite-code header on the request that creates the user
await authClient.signIn.emailOtp(
  { email, otp },
  { headers: { "x-invite-code": inviteCode } },
);

The header is the typed way for better-auth's client; an inviteCode field in the sign-up body works too, for plain HTTP requests such as an HTML form.

Auth server on another domain?

x-invite-code is a custom header. If your app and your auth server run on different origins, the browser only sends it when the server's CORS configuration allows it (Access-Control-Allow-Headers). Add the header there. Social sign-in (additionalData) and the body field need no extra header.

A magic link creates the user when the link from the email is opened, a request your app doesn't control, so requireInviteCode doesn't work with magic link sign-up.

Blocklist

With the blocklist plugin, blocked emails (disposable domains, for example) can't join the waitlist or be invited: join and createInvite answer EMAIL_NOT_ALLOWED, instead of the email failing only at sign-up.

Rate limits

The public endpoints (join, confirm, get-status, leave, check-invite) are limited to 5 requests per minute per IP by better-auth's rate limiter, which is on in production by default. A person joins once or twice; the limit is there to slow down bots. Change it with rateLimit.customRules, which take precedence over plugin rules:

auth.ts
betterAuth({
  rateLimit: {
    customRules: { "/waitlist/join": { window: 60, max: 10 } },
  },
});

More than one server? Share the rate limit's storage

better-auth counts requests in memory by default, per server process. With several instances or serverless functions, every instance keeps its own count, so the real limit is 5 per minute per instance and barely slows down guessing. Store the counts where all instances see them, with rateLimit.storage: "database" or "secondary-storage" (Redis, for example). The limiter is also off in development unless you set rateLimit.enabled: true.

Capacity

maxEntries (unlimited by default) caps how many people are waiting: pending and approved entries. Once the waitlist holds that many, joining and confirming fail with WAITLIST_FULL, for every email. Other entries don't count: unconfirmed ones, so fake sign-ups can't fill the waitlist (they expire after confirmationExpiresIn), and rejected and registered ones, which have left it. Rejecting an entry, or an approved user signing up, frees a place.

The limit holds under concurrent requests too: a join or confirmation that finds the waitlist over maxEntries once its entry is written takes the entry back (a confirmed entry goes back to unconfirmed) and fails with WAITLIST_FULL. When several requests race for the last place, all of them may fail; the place stays free for the next try.

Privacy

Not legal advice

A waitlist stores email addresses, which is personal data. Keep double opt-in on, so you can show that every person asked to be contacted; mention the waitlist in your privacy policy; and put the leave link in your emails, so people can leave the waitlist and have their entry deleted.

Consent. A confirmed entry shows that someone controlled the email address and opened the link, and confirmedAt says when. It doesn't record what they agreed to. If consent is your legal basis, also keep the consent statement or notice version they saw: pass it as metadata when they join, and it is stored with the entry:

await authClient.waitlist.join({
  email: "ada@example.com",
  metadata: { consent: "waitlist-emails", noticeVersion: "2026-11" },
});

With the audit log, confirmations (waitlist.confirmed) and people leaving (waitlist.left) are recorded there too, so the record of a withdrawal remains after the entry is deleted. These events hold the email address, so they stay personal data until the audit log's retention deletes them.

Cleanup. Unconfirmed entries whose link has expired are deleted, and with retention, rejected and registered entries after a number of days:

auth.ts
waitlist({
  // ...
  retention: { rejected: 90, registered: 30 }, // days
});
  • Rejected entries are deleted rejected days after they were rejected. The email can then join again.
  • Registered entries are deleted registered days after the account was created. The user keeps their account.
  • When a user is deleted, their entry is deleted with them, whatever its status.
  • Pending and approved entries are never deleted automatically: those people are still waiting.

The cleanup runs in the background, at most once an hour (retention.sweepInterval, in seconds), started by any waitlist request. Joining also deletes expired unconfirmed entries right away. On serverless platforms, configure better-auth's advanced.backgroundTasks so it can finish, or run it from a cron job with the server-only deleteExpiredWaitlistEntries:

cron.ts
const { deleted } = await auth.api.deleteExpiredWaitlistEntries();

Without retention, rejected and registered entries stay until someone leaves or an admin deletes them.

Managing the waitlist

The admin endpoints require a session whose user has one of adminRoles (the role field of better-auth's admin plugin) or is listed in adminUserIds. Requests without a session get a 401, other users a 403.

// entries in the order they joined, oldest first
const { data } = await authClient.waitlist.listEntries({
  query: { status: "pending", search: "example.com", limit: 50, offset: 0 },
});
// data: { entries, total }

// approve the next 10 pending entries, or specific ones with { ids: [...] }
await authClient.waitlist.approveEntries({ count: 10 });

await authClient.waitlist.rejectEntry({ id: "entry-id" });
await authClient.waitlist.deleteEntry({ id: "entry-id" });

// invite someone directly, whether or not they are on the waitlist
await authClient.waitlist.createInvite({ email: "guest@example.com" });

const { data: stats } = await authClient.waitlist.getStats();
// stats: { unconfirmed, pending, approved, rejected, registered, total }
  • Renewing an invite: approve an approved entry again, for example when the person lost the email or the invite expired. They get a new code with a new expiry, and the old code stops working.
  • approveEntries skips unconfirmed entries (they haven't agreed to be contacted) and registered ones.
  • Rejecting an entry invalidates its invite.
  • Concurrent changes: approving, renewing, and rejecting only apply while the entry is as it was read, so two admins approving the same entry at once send one invite, and a rejection never overwrites a sign-up that happened meanwhile. approveEntries skips an entry that another request changed first; rejectEntry and createInvite fail with 409 ENTRY_CHANGED, to retry after loading the entry again.
  • Entries come back without their token: only the person gets it, by email.
  • inviteCode is the plain code only in the responses of approveEntries and createInvite, which issue it (to share it another way than sendInvite); everywhere else it is null, because only its hash is stored.
EndpointClientServer
POST /waitlist/joinauthClient.waitlist.joinauth.api.joinWaitlist
POST /waitlist/confirmauthClient.waitlist.confirmauth.api.confirmWaitlistEmail
GET /waitlist/get-statusauthClient.waitlist.getStatusauth.api.getWaitlistStatus
POST /waitlist/leaveauthClient.waitlist.leaveauth.api.leaveWaitlist
GET /waitlist/check-inviteauthClient.waitlist.checkInviteauth.api.checkWaitlistInvite
GET /waitlist/list-entriesauthClient.waitlist.listEntriesauth.api.listWaitlistEntries
GET /waitlist/get-statsauthClient.waitlist.getStatsauth.api.getWaitlistStats
POST /waitlist/approve-entriesauthClient.waitlist.approveEntriesauth.api.approveWaitlistEntries
POST /waitlist/reject-entryauthClient.waitlist.rejectEntryauth.api.rejectWaitlistEntry
POST /waitlist/delete-entryauthClient.waitlist.deleteEntryauth.api.deleteWaitlistEntry
POST /waitlist/create-inviteauthClient.waitlist.createInviteauth.api.createWaitlistInvite
(server only)-auth.api.deleteExpiredWaitlistEntries

With the audit log

With the audit log plugin, confirmations, approvals, rejections, deleted entries, and people leaving are recorded there too (see Events from other plugins).

Schema

Table: waitlistEntry

Prop

Type

To rename the table or its columns, use the schema option:

auth.ts
waitlist({
  schema: {
    waitlistEntry: {
      modelName: "waitlist_entries",
      fields: { createdAt: "created_at" },
    },
  },
});

Error codes

Exported as WAITLIST_ERROR_CODES from both entry points, to compare with error.code:

import { WAITLIST_ERROR_CODES } from "@checodo/better-auth-waitlist/client";

if (error?.code === WAITLIST_ERROR_CODES.EMAIL_NOT_APPROVED.code) {
  // show "You're on the waitlist, we'll email you"
}
CodeStatusWhen
EMAIL_NOT_APPROVED403Creating a user for an email that isn't approved
INVITE_CODE_REQUIRED403Signing up without a code, with requireInviteCode
INVALID_INVITE_CODE403Signing up with a code that isn't this email's valid invite, with requireInviteCode
INVALID_TOKEN400Confirm, status, or leave with an unknown or expired token
WAITLIST_FULL403Joining or confirming while the waitlist holds maxEntries
ENTRY_NOT_FOUND404Rejecting or deleting an entry that doesn't exist
ENTRY_CHANGED409Rejecting or inviting while another request changes the same entry
METADATA_TOO_LARGE400Joining with more than 2,000 characters of JSON metadata
YOU_ARE_NOT_ALLOWED_TO_MANAGE_WAITLIST403Admin endpoints, for users who aren't admins

Options

Prop

Type

On this page