Identity tokens
Access user data securely with Privy identity tokens
Identity tokens provide a secure and efficient way to access user data, especially on the server side. These tokens are JSON Web Tokens (JWTs) whose claims contain information about the currently authenticated user, including their linked accounts, metadata, and more.
Privy strongly recommends using identity tokens when you need user-level data on your server. They allow you to easily pass a signed representation of the current user’s linked accounts from your frontend to your backend directly, letting you verifiably determine which accounts (wallet address, email address, Farcaster profile, etc.) are associated with the current request.
Enabling identity tokens
To enable identity tokens for your application:
- Navigate to your application dashboard’s User management > Authentication > Advanced section
- Toggle on Return user data in an identity token on the Basics page
- Make sure you’re using the latest version of the Privy SDK
Token Format
Privy identity tokens are JSON Web Tokens (JWT), signed with the ES256 algorithm. These JWTs include the following claims:
A stringified array containing a lightweight version of the current user’s linkedAccounts
A stringified version of the current user’s customMetadata
The user’s Privy DID
The token issuer, which should always be privy.io
Your Privy app ID
The timestamp of when the JWT was issued
The timestamp of when the JWT will expire (generally 1 hour after issuance)
Retrieving identity Tokens
Once you’ve enabled identity tokens, Privy will automatically include the identity token as a cookie on every request from your frontend to your server.
For setups where you cannot use cookies, you can retrieve the identity token using the useIdentityToken
hook:
We strongly recommend setting a base domain for your application, so that Privy can set the identity token as a more secure HttpOnly cookie.
Reading identity tokens on your server
On your server, you can retrieve the identity token from incoming requests and use it to identify the user.
Accessing custom metadata
Privy allows you to set custom metadata for a user via backend API requests. This metadata is available in the custom_metadata
claim of the identity token.
Here’s how to parse and access it:
Refreshing the identity token
A new identity token is automatically issued when a user:
- Authenticates into the application
- Links or unlinks an account
- Refreshes their application page
- Calls
getAccessToken
when the access token is expired
To programmatically refresh the identity token, call refreshUser
from the useUser
hook:
Verifying the identity token
When your server receives a request with an identity token, you should verify the token’s signature to authenticate the user. The preferred way is to use the getUser
method from @privy-io/server-auth
, which handles verification and parsing:
The verifyAuthToken
method will not work on identity tokens, as it is only used to verify Privy
access tokens. Always use getUser({idToken})
when working with identity tokens.
For manual verification without using getUser
, you can use JWT libraries like jose
:
Security Considerations
For optimal security when working with identity tokens:
- Always verify the token signature before trusting any claims
- Check the expiration time (
exp
claim) to ensure the token is still valid - Set a base domain for your application to enable HttpOnly cookies for the identity token
- Use HTTPS for all communication between your frontend and backend
- Do not store sensitive information in custom metadata, as it will be included in the identity token
Was this page helpful?