Authentication
You can set up your authentication configuration in the Configuration page of the Privy Console. In the Privy Console, find your app in the dropdown on the left and navigate to the Configuration page from the left sidebar. In this page, you can optionally set your WalletConnect project ID, configure your domain allowlist, and/or set up cookies.
Configure your allowed domains
You should always restrict allowed origins for any production application.
Set the domains which can use your client-side App ID. You must include the protocol as well, e.g. https://. This is recommended as a security best-practice.
Configure your domain allowlist in the console.
Note that this domain allowlist restricts client-side access only. Server API endpoints are gated by access to the Privy app secret.
Setting up cookies
If your app uses server-side rendering (SSR) and needs to access a user's session from the server, you should set up cookies in addition to configuring allowed domains (outlined above) for your app.
Otherwise, you can get started easily using the default local storage.
When a user logs in to your app, Privy issues that user an auth token that stores their authenticated session.
You can configure Privy to store a user's auth token either with a browser's local storage or cookies. Privy uses local storage by default. To configure your app to use cookies, follow the steps below:
1. Create two Privy Apps with distinct App IDs
In the Privy Console, create (at minimum) two Privy Apps. Concretely, you should create one app for use in production environments only, and one app for use in development environments only. We suggest you label which app is your development environment via that app's name.
This step is critical, as once you enable cookies, your production App ID will only work in your production environment, and will error in all other environments.
The development process for all environments (production and development) will be the same on your end. The only difference is that you must use separate App IDs for each environment.
Next, follow the steps below, only for your production app. Do not complete them for your development app.
2. For your production app, register your production domain in the Privy Console
In the Privy Console, find your production app in the App Dropdown of the left sidebar. Then, navigate to the Configuration page for that app.
In the Server-Side Rendering section of the page, enter your app's domain. Include the root domain, but not the protocol or www. Then, click Add domain. Privy will verify your domain within 24 hours and update its status in the console once complete.
Once your domain is verified, the corresponding App ID can only be used on that exact production domain.
3. For your production domain, add a Privy CNAME record to your domain registrar
Go to the admin console of your domain registrar and create a CNAME record for your production domain with the following properties:
- Type:
CNAME - Name:
privy - Value:
cname.vercel-dns.com
This allows Privy's servers to set a first-party cookie on your production domain. Once this is completed, it may take a few hours for the DNS to take effect.
That's it! Once you've finished the steps above, Privy will review your request and update servers to begin setting cookies on your production app's domain.
4. Using cookies in production vs. development environments
In both production and development (local, preview, staging) environments, Privy will set a cookie with the name privy-token to store your user's session. Your app logic for handling the cookie (e.g. in your authorization middleware) does not need to handle different environments differently.
The mechanics of how the cookie is the key difference between production and development environments. This is why you must only use your production App ID within your production environment.
Concretely:
- For your production App ID, once you have completed the steps above, Privy's servers will set a cookie, only on the domain you have verified and any subdomains. Cookies will not be set on localhost.
- For your development App ID(s), Privy's client will automatically set a cookie on any domain you use this App ID on, including localhost. This allows you to use the same app logic around cookies across various environments. As a security precaution, client-set cookies for development have a shorter lifetime (7 days, versus 30 days for server-set cookies).