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
• 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.

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:

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:

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.