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 strongly encourages enabling and using identity tokens for your application when you need user-level data on you server. They allow you to easily pass a signed representation of the current user's linked accounts from your frontend to your backend directly. 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 their claims, namely:

  • linked_accounts is a stringified array containing a lightweight version of the current user's user.linkedAccounts field
  • custom_metadata is a stringified version of the current user's user.customMetadata 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.

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 getUserFromRequest(req: NextApiRequest) {
  const idToken = req.cookies.get('privy-id-token');
  try {
    const user = await getUser({idToken: idToken})
    return user;
  } 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.

For setups where you cannot use cookies, you can also retrieve the identity token from the client by using the useIdentityToken hook:

tsx
import {useIdentityToken} from '@privy-io/react-auth';

const {identityToken} = useIdentityToken();

Refreshing the identity token ​

Any time a user:

  • authenticates into the application,
  • links/unlinks an account,
  • refreshes their application page,
  • or calls getAccessToken when the access token is expired,

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

In order to programmatically refresh the identity token, simply call refreshUser from the useUser hook.

Custom metadata in the identity token ​

Privy allows for you to set custom metadata for a user via backend API requests. This metadata is available as a stringified JSON in the custom_metadata claim of the identity token, which you can retrieve and parse like so:

tsx
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) {
    const customMetadata = JSON.parse(payload.custom_metadata);
  }
  // ...
} catch (error) {
  // ...
}

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.