With Privy, you can enable an allowlist for your application to gate access to specific email addresses, phone numbers, and/or wallet addresses. You can use the allowlist feature to coordinate a beta launch of your product for early-access users, manage an ongoing waitlist, and more! When you enable an allowlist for your app:

All existing users will still be permitted to login to your app
New users must be added to the allowlist by their email address, phone number, or wallet address to be permitted to login
New users who have not been added to your allowlist will not be permitted to login.

Allowlists apply to email, SMS, wallet, and OAuth methods with verified emails only. Login methods like Telegram and Farcaster are not supported.

Enabling the allowlist for your app

You can enable an allowlist directly from the Privy developer dashboard. To do so, just navigate to the Users page > Access Control tab of the dashboard and toggle allowlists on.

Managing the allowlist

There are two main ways to manage the allowlist for your app:

Using the API, you can easily add users, remove users, and get your current allowlist.
Using the developer dashboard, you can easily add and remove users from your app’s invite list page.

It’s easy to use the Privy API to manage your waitlist with a third party-tool. For instance, if you are using Airtable to manage your waitlist, you can easily integrate it with Privy.Check out this guide for more!

Adding to the allowlist

Privy allows you to easily add a user’s email address, phone number, or wallet address to the allowlist for your app.

Use the inviteToAllowlist method from the apps() interface to add a user to your allowlist.

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!
});

const allowlistEntry = await privy.apps().inviteToAllowlist({
  type: 'email',
  value: '[email protected]'
});

As a parameter to the method, pass an object with the following fields:

'email' | 'phone' | 'wallet'

required

The type of account to add to the allowlist.

string

required

The identifier of the account to add to the allowlist. Should be the corresponding email address, phone number, or wallet address.

If the invitation is successful, the method returns an allowlist entry object. If the invitation fails, the method throws an error.

Removing from the allowlist

Privy allows you to easily remove a user’s email address, phone number, or wallet address to the allowlist for your app.

Use the removeFromAllowlist method from the apps() interface to remove a user from your allowlist.

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!
});

const removedAllowlistEntry = await privy.apps().removeFromAllowlist({
  type: 'email',
  value: '[email protected]'
});

As a parameter to the method, pass an object with the following fields:

'email' | 'phone' | 'wallet'

required

The type of account to remove from the allowlist.

string

required

The identifier of the account to remove from the allowlist. Should be the corresponding email address, phone number, or wallet address.

If the removal is successful, the method returns a confirmation object. If the removal fails, the method throws an error.

If a user has successfully logged into your application (e.g. after having been added to the allow list), you must delete their user object, rather than deleting their allowlist entry—to revoke their access.

Getting the allowlist

Privy allows you to easily get the current allowlist for your app.

Use the getAllowlist method from the apps() interface to get your app’s current allowlist. Pass no parameters to this method.

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!
});

const allowlist = await privy.apps().getAllowlist();

If the request is successful, the method returns an array of allowlist entry objects. Each entry includes an id, a type describing the type of entry ('email', 'phone', or 'wallet'), a value with the corresponding account identifier, and an appId.

Customizing allowlist rejection

If your app has an allowlist enabled, new users who attempt to login with an account not in your allowlist will not be permitted to login to your app. You can customize the screen shown to the user when they are denied permission to login, to help contextualize the allowlist within your app. To customize this screen, make a POST request to

https://auth.privy.io/api/v1/apps/<your-privy-app-id>

In the body of the request, include an field that contains a JSON with the following fields. All fields in this object are optional.

string

The primary text for the error message you’d like to show your user. Defaults to “You don’t have access to this app”.

string

The secondary text for the error message you’d like to show your user. Defaults to “Have you been invited?”

string

The text to show on the error confirmation button. Defaults to “Try another account”

string

The URL to navigate the user to, when they click the error CTA. Defaults to just closing the screen on click, instead of navigating the user to another URL.

Below is a sample cURL command for updating the allowlist config:

curl --request POST 'https://auth.privy.io/api/v1/apps/<your-privy-app-id>' \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
--data-raw '{
  "allowlist_config": {
    "error_title": "Insert your error title",
    "error_detail": "Insert your error detail",
    "cta_text": "Insert your error CTA",
    "cta_link": "Insert a URL to navigate the user to when clicking the CTA"
  }
}'

Users

User management

Managing users

Migrating users to Privy

Webhooks

Allowlist

Enabling the allowlist for your app

Managing the allowlist

Adding to the allowlist

Removing from the allowlist

Getting the allowlist

Customizing allowlist rejection

​Enabling the allowlist for your app

​Managing the allowlist

​Adding to the allowlist

​Removing from the allowlist

​Getting the allowlist

​Customizing allowlist rejection

Enabling the allowlist for your app

Managing the allowlist

Adding to the allowlist

Removing from the allowlist

Getting the allowlist

Customizing allowlist rejection