Appearance

Identity token ​

Identity tokens are a type of JSON Web Token (JWT) whose token claims contain information about the currently authenticated user, including their linked accounts, metadata, and more. You can learn more about identity tokens here.

Privy supports enabling identity tokens for your application, which allows you to easily pass a signed representation of the current user's linked accounts from your frontend to your server. This allows you to easily and verifiably determine which accounts (wallet address, email address, Farcaster profile, etc.) are associated with the current request.

Enabling identity tokens ​

You can enable identity tokens to be returned in your application by navigating to your application dashboard's Settings section and toggling Return user data in an identity token.

Token format ​

Privy identity tokens are JSON Web Tokens (JWT), signed with the ES256 algorithm. These JWTs include certain information about the user object in its claims, namely:

  • linked_accounts is a stringified array containing a lightweight version of the current user's user.linkedAccounts field
  • sub is the user’s Privy DID
  • iss is the token issuer, which should always be privy.io
  • aud is your Privy app ID
  • iat is the timestamp of when the JWT was issued
  • exp is the timestamp of when the JWT will expire and is no longer valid. This is generally 1 hour after the JWT was issued.

INFO

Read more about Privy's tokens and their security in our security guide.

Retrieving the identity token ​

Once you have enabled identity tokens for your application, Privy will automatically include the identity token as a cookie on every request from your frontend to your server. Any time a user:

  • authenticates into the application,
  • links/unlinks an account,
  • refreshes their application page,
  • or calls getAccessToken

A new, updated identity token will be issued to the user.

Then, from your server, you can get the current user's identity token by retrieving the cookie attached to any network request from your front-end application. As an example in NextJS:

tsx
export async function handleIdentityToken(req: NextApiRequest) {
  const cookieIdentityToken = req.cookies.get('privy-id-token');
  // Use a JWT decoding/verification library like jose to verify and extract claims from the identity token
  try {
  const {payload, protectedHeader } = await jose.jwtVerify(cookieIdentityToken, verificationKey, {
    issuer: 'privy.io',
    audience: 'insert-your-privy-app-id',
  });
  if (payload) {
    // use the payload (decrypted JWT) to query for user parameters
  }
  console.log(payload);
} catch (error) {
  console.error(error);
}

TIP

We strongly recommend setting a base domain for your application, so that Privy can set the identity token as a more secure HttpOnly cookie.

Verifying the identity token ​

When a request is received by your backend with the identity token, you should make sure to verify the user's identity token's signature to identify the user. The verifyAuthToken method will not work on the identity token, as it is only used to verify the Privy access token.