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-waitlistAdd 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).
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}`,
});
},
}),
],
});Add the client plugin
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 anotherconfirmationExpiresIn, 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:
onJoinandautoApproverun once. - The entry's
confirmedAtrecords when the link was opened. It staysnullwhen 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 aswaitlist.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
| Status | Meaning |
|---|---|
unconfirmed | Joined, but hasn't confirmed the email yet |
pending | On the waitlist, waiting for approval |
approved | May create an account until the invite expires |
rejected | May not create an account |
registered | Created 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 (nulloutside a request). By default, users created by admins through the admin plugin'screateUserskip the waitlist.
Users without a real email are blocked too, because their generated email is never on the waitlist:
| Sign-in method | Generated email |
|---|---|
| Anonymous guests | temp-...@<emailDomainName> |
| Phone number sign-up on verification | what 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:
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:
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:
waitlist({
// ...
retention: { rejected: 90, registered: 30 }, // days
});- Rejected entries are deleted
rejecteddays after they were rejected. The email can then join again. - Registered entries are deleted
registereddays 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:
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.
approveEntriesskipsunconfirmedentries (they haven't agreed to be contacted) andregisteredones.- 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.
approveEntriesskips an entry that another request changed first;rejectEntryandcreateInvitefail with409 ENTRY_CHANGED, to retry after loading the entry again. - Entries come back without their
token: only the person gets it, by email. inviteCodeis the plain code only in the responses ofapproveEntriesandcreateInvite, which issue it (to share it another way thansendInvite); everywhere else it isnull, because only its hash is stored.
| Endpoint | Client | Server |
|---|---|---|
POST /waitlist/join | authClient.waitlist.join | auth.api.joinWaitlist |
POST /waitlist/confirm | authClient.waitlist.confirm | auth.api.confirmWaitlistEmail |
GET /waitlist/get-status | authClient.waitlist.getStatus | auth.api.getWaitlistStatus |
POST /waitlist/leave | authClient.waitlist.leave | auth.api.leaveWaitlist |
GET /waitlist/check-invite | authClient.waitlist.checkInvite | auth.api.checkWaitlistInvite |
GET /waitlist/list-entries | authClient.waitlist.listEntries | auth.api.listWaitlistEntries |
GET /waitlist/get-stats | authClient.waitlist.getStats | auth.api.getWaitlistStats |
POST /waitlist/approve-entries | authClient.waitlist.approveEntries | auth.api.approveWaitlistEntries |
POST /waitlist/reject-entry | authClient.waitlist.rejectEntry | auth.api.rejectWaitlistEntry |
POST /waitlist/delete-entry | authClient.waitlist.deleteEntry | auth.api.deleteWaitlistEntry |
POST /waitlist/create-invite | authClient.waitlist.createInvite | auth.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:
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"
}| Code | Status | When |
|---|---|---|
EMAIL_NOT_APPROVED | 403 | Creating a user for an email that isn't approved |
INVITE_CODE_REQUIRED | 403 | Signing up without a code, with requireInviteCode |
INVALID_INVITE_CODE | 403 | Signing up with a code that isn't this email's valid invite, with requireInviteCode |
INVALID_TOKEN | 400 | Confirm, status, or leave with an unknown or expired token |
WAITLIST_FULL | 403 | Joining or confirming while the waitlist holds maxEntries |
ENTRY_NOT_FOUND | 404 | Rejecting or deleting an entry that doesn't exist |
ENTRY_CHANGED | 409 | Rejecting or inviting while another request changes the same entry |
METADATA_TOO_LARGE | 400 | Joining with more than 2,000 characters of JSON metadata |
YOU_ARE_NOT_ALLOWED_TO_MANAGE_WAITLIST | 403 | Admin endpoints, for users who aren't admins |
Options
Prop
Type