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

When you enable an allow list for your app:

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

​
Enabling the allow list for your app

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

​
Managing the allow list

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

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 allow list

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

Use the ‘s method to add a user to your allow list.

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

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

​
type
'email' | 'phone' | 'wallet'
required

The type of account to add to the allow list.

​
value
string
required

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

If the invitation is successful, the method will return an . If the invitation fails, the method will throw an error.

​
Removing from the allow list

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

Use the ‘s method to remove a user from your allow list.

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

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

​
type
'email' | 'phone' | 'wallet'
required

The type of account to remove from the allow list.

​
value
string
required

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

If the invitation is successful, the method will return an that represents the now-deleted allow list entry. If the invitation fails, the method will throw 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 allow list entry—to revoke their access.

​
Getting the allow list

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

Use the ‘s method to get your app’s current allow list. Pass no parameters to this method.

const allowlistEntry = await privy.getAllowlist();

If the request is successful, the method will return an array of objects. These include a type describing the type of entry ('email', 'phone', or 'wallet') and a value with the corresponding account identifier (e.g. the email address).

​
Customizing allow list rejection

If your app has an allow list enabled, new users who attempt to login with an account not in your allow list 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 allow list 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.

​
error_title
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”.

​
error_detail
string

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

​
cta_text
string

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

​
cta_link
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 allow list 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"
  }
}'