Appearance

Identity tokens in Expo ​

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. Then, you must be on @privy-io/expo SDK version 0.21.6 or higher to enable identity tokens.

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
  • 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. 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 be issued to the user.

You can get the current user's Privy token as a string using the getIdentityToken method from the useIdentityToken hook.

tsx
const {getIdentityToken} = useIdentityToken();
const idToken = await getIdentityToken();

For authenticated users, getIdentityToken returns a Promise on valid identity token for the user. For unauthenticated users, getIdentityToken returns null.

You can then include the returned idToken in the header of a request, like so:

tsx
const response = await fetch(<your-api-route>, {
    method: <your-request-method>
    body: <your-request-body>,
    headers: {
        'privy-id-token': idToken, 
        /* Add any other request headers you'd like */
    }
});

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

tsx
export async function handleIdentityToken(req: NextApiRequest) {
  const idToken = req.headers.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(idToken, 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);
}

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.