Waitlist
Review and approve signup requests before granting access to your application.
The waitlist collects signup requests and lets you review them before users can register. This is useful for gated launches, closed betas, or any application that requires vetting users before they can sign up.
When the waitlist is enabled, the AuthKit signup form is replaced with a form that collects the user’s email and adds them to the waitlist. Each entry can be approved or denied individually from the WorkOS dashboard, programmatically with the Waitlist API, or by asking an AI agent connected to the WorkOS MCP server.
When a user joins the waitlist from the AuthKit signup form, a pending entry is created for their email address. From the “Waitlist” tab in the “Users” section of the WorkOS dashboard, each entry can be:
- Approved. The user receives an invitation email with a link to complete their signup.
- Denied. The entry is marked as denied and the user is not notified.
The invitation sent on approval is independent of the waitlist entry. Deleting the entry through the API does not revoke the invitation, so the recipient can still use it to sign up. To withdraw access, revoke the invitation.
Waitlists are scoped to an environment, so entries collected in a staging environment are kept separate from production. Each environment has a single default waitlist that entries are added to.
When the waitlist is enabled, users cannot register for a new account themselves – AuthKit shows the waitlist form instead of the signup form. Existing users can still sign in, and you can still create users with your secret API key: the waitlist gates self-service sign-up, not user creation from your backend.
The following users can still sign up:
- Invited users. When a valid invitation code is present in the sign-in flow, registration is opened up so that the invited user may sign up. See Invitations for details on sending and accepting invitations.
- Users with verified email domains. If the user’s email domain matches a verified domain of an organization with JIT provisioning enabled, a new user is created and added to the organization. Pre-configured domain access is honored so members of known organizations aren’t routed through the waitlist.
Enable the waitlist per environment from the Authentication → Features page of the WorkOS dashboard. Select Enable on the “Waitlist” card. While the waitlist is enabled, the sign-up setting for the environment is superseded and AuthKit shows the waitlist form in place of the signup form.
An entry can carry additional information beyond the email address, such as the user’s name, their company, or how they plan to use your application. The AuthKit waitlist form collects only an email address, so additional fields are set by creating the entry with the API from your own form.
Additional fields are stored on the entry as key/value pairs. They appear alongside the entry in the dashboard, are included in CSV exports, and are returned on every entry response and webhook payload. Each entry supports up to 50 fields, with keys up to 40 characters and values up to 600 characters.
When a user joins the waitlist through AuthKit, WorkOS sends them a confirmation email letting them know their request was received. The confirmation email is sent only the first time an email address joins the waitlist.
The confirmation email is enabled by default and can be turned off per environment. Navigate to Emails → Configuration in the dashboard, select Manage, and toggle the waitlist confirmation email setting. The setting is shown once the waitlist is enabled for the environment.
The setting governs every way an entry is created. While it is off, no confirmation email is sent for entries created through the API either, even when the request asks for one.
Approving an entry creates an invitation for the entry’s email address and sends the standard invitation email with a link to complete signup. The invitation email can be customized or sent by your application like any other invitation.
Denying an entry marks it as denied and does not notify the user. The user’s email address remains on the waitlist in the denied state, so they cannot rejoin. Only pending entries can be denied, but a denied entry can still be approved later – approval lifts the denial and sends the invitation.
WorkOS emits webhook events when waitlist entries change state:
waitlist_user.created– a new user joined the waitlist.waitlist_user.approved– an entry was approved.waitlist_user.denied– an entry was denied.
Each event’s data is the waitlist entry, with the same fields the Waitlist API returns, including any additional fields on the entry. For historical reasons the event names and the payload’s object field use waitlist_user, while the API returns the same record as waitlist_entry.
Subscribe to these events by creating a webhook endpoint in the WorkOS dashboard. This lets you plug the waitlist into review workflows in other systems, such as auto-approving entries from known email domains or notifying a Slack channel when new entries arrive.
Waitlist entries can be exported as a CSV file from the “Waitlist” tab in the “Users” section of the dashboard. Select Export CSV to download the entries matching the current search, state, and date filters. Each row contains the entry’s ID, email, state, creation time, and approval time, followed by a column per additional field, prefixed with additional_field_.
The Waitlist API manages waitlists and their entries programmatically. Requests are authenticated with your environment’s secret API key as a Bearer token, so call the API from your backend – for example, submit your own waitlist form to your server and create the entry from there. Never expose the secret key in browser or mobile code. Wherever a waitlist ID appears in a path, the literal ID default refers to the environment’s default waitlist. See the Waitlist API reference for the full specification: