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'suser.linkedAccounts
fieldcustom_metadata
is a stringified version of the current user'suser.customMetadata
fieldsub
is the user’s Privy DIDiss
is the token issuer, which should always be privy.ioaud
is your Privy app IDiat
is the timestamp of when the JWT was issuedexp
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.