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. images/Allow.png

​
Managing the allowlist

There are two main ways to manage the allowlist 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 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 ‘s method to add a user to your allowlist.
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 allowlist.
​
value
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 will return an . If the invitation fails, the method will throw 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 ‘s method to remove a user from your allowlist.
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 allowlist.
​
value
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 invitation is successful, the method will return an that represents the now-deleted allowlist 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 allowlist entry—to revoke their access.

​
Getting the allowlist

Privy allows you to easily get the current allowlist for your app.
Use the ‘s method to get your app’s current allowlist. 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 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.
​
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 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"
  }
}'