HttpOnly
cookie set on your app’s base domain.
By default, Privy will store the user’s access token in local storage. Configuring cookies requires that your app have a stable base domain and that you set a DNS record for this domain. In kind, cookies are recommended for production applications only.
While developing your integration, you can use Privy’s default setup of local storage to get started.
*.vercel.app
, *.railway.app
, *.herokuapp.com
, and *.amazonaws.com
.
acme_challenge
and state resets, you might either:
CAA
record on your root domain (ie example.com
, not including any subdomains). If there are already contents in the CAA
record, append the following, otherwise create a new record containing the following:
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 set 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:
localhost
environment, you can do so by using App Clients.
privy-token
cookie.
If your app uses server-side rendering (SSR), you can use the presence of this cookie (and other Privy cookies) to determine if the user is authenticated before your page is rendered on the client.
privy-token
is presentprivy-token
, you should consider the user as authenticated and should handle them accordingly.
privy-token
is absentprivy-token
, the user might either:
login
to become unauthenticated.privy-token
, as it has expired, but the privy-token
will be refreshed imminently as soon as the page loads in the user’s browser.
To handle this case, when the privy-token
is missing in the request, you should instead wait for your app to load in the client, to allow their user’s authentication status to update correctly, before taking any actions based on their authentication status. This most commonly occurs in middleware setups that perform server-side routing.
One solution for handling this flow is to set up your app and middleware like so:
/refresh
) that implements the following:
getAccessToken
method when the page loads. This ensures that whenever the user visits this page, their session is refreshed if they are authenticated.getAccessToken
returns a valid token, redirect the user to the path specified in a redirect_uri
query parameter. Your middleware will populate this query parameter later.getAccessToken
returns null
, redirect the user to your login page as they are not authenticated.privy-token
that is valid, you can consider the user authenticated and apply your normal middleware.privy-token
but does include a privy-session
cookie, the user may be authenticated, and you’ll need to refresh their session from the client before applying your middleware./refresh
page you set up above. As part of this, you should also pass the original route the user intended to visit as a query param (e.g. redirect_url
) when you redirect them to /refresh
. Per the client-side setup, this allows the user’s session to be refreshed and for them to be correctly redirected based on their authentication status./refresh
path you setup: in this case, the user should be allowed to visit the /refresh
page as their authentication status and redirect will be handled on that page in the client. Redirecting away from this page in your middleware may result in an infinite redirecting loop.privy_oauth_code
, privy_oauth_state
, or privy_oauth_provider
: these parameters are a required component of Privy’s OAuth login flow and applying a redirect will destructively erase them.SameSite
attribute set to Strict
.
This ensures that cookies are only sent on requests originating from the same site that set the cookie.
However, you may wish to receive cookies on cross-site top-level navigations or safe requests methods (e.g. GET
, HEAD
, OPTIONS
).
In this case, you can toggle setting the SameSite
attribute to Lax
in the Privy Dashboard.