Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.privy.io/llms.txt

Use this file to discover all available pages before exploring further.

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.
Enable identity tokens in the Privy Dashboard before implementing this feature.

​
Enabling identity tokens

To enable identity tokens for your application:
  1. Navigate to your application dashboard’s User management > Authentication > Advanced section
  2. Toggle on Return user data in an identity token
  3. 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:

​
Retrieving identity tokens

​
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: 
import {PrivyClient} from '@privy-io/node';
import * as jose from 'jose';

const client = new PrivyClient({appId: '$PRIVY_APP_ID', appSecret: '$PRIVY_APP_SECRET'});

// Method 1: Using get (recommended)
async function getUserWithMetadata(idToken: string) {
  const user = await client.users().get({id_token: idToken});
  // Custom metadata is already parsed and available
  return user.custom_metadata;
}

// Method 2: Manual parsing
async function parseCustomMetadata(idToken: string) {
  const verificationKey = await jose.importJWK({}); /* your verification key */

  try {
    const {payload} = await jose.jwtVerify(idToken, verificationKey, {
      issuer: 'privy.io',
      audience: 'your-privy-app-id'
    });

    if (payload && payload.custom_metadata) {
      return JSON.parse(payload.custom_metadata as string);
    }

    return {};
  } catch (error) {
    console.error('Error parsing identity token:', error);
    throw error;
  }
}

​
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

​
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 the @privy-io/node SDK, which handles verification and parsing: 
import {PrivyClient} from '@privy-io/node';

const client = new PrivyClient({appId: '$PRIVY_APP_ID', appSecret: '$PRIVY_APP_SECRET'});

async function verifyAndGetUser(idToken) {
  try {
    // This verifies the token signature and parses the payload
    const user = await client.users().get({id_token: idToken});
    return user;
  } catch (error) {
    console.error('Invalid identity token:', error);
    throw new Error('Authentication failed');
  }
}
The verifyAuthToken method will not work on identity tokens, as it is only used to verify Privy access tokens. Always use get({id_token}) when working with identity tokens.
For manual verification without using get, you can use JWT libraries like jose: 
import * as jose from 'jose';

async function verifyIdentityToken(idToken) {
  // Import the public key
  const publicKey = await jose.importJWK({
    // Your public key in JWK format
  });

  try {
    // Verify the token
    const {payload} = await jose.jwtVerify(idToken, publicKey, {
      issuer: 'privy.io',
      audience: 'your-privy-app-id'
    });

    return payload;
  } catch (error) {
    console.error('Token verification failed:', error);
    throw new Error('Authentication failed');
  }
}

​
Security considerations

For optimal security when working with identity tokens:
  1. Always verify the token signature before trusting any claims
  2. Check the expiration time (exp claim) to ensure the token is still valid
  3. Set a base domain for your application to enable HttpOnly cookies for the identity token
  4. Use HTTPS for all communication between your frontend and backend
  5. Do not store sensitive information in custom metadata, as it will be included in the identity token
Read more about Privy’s tokens and their security in our security guide.