Appearance

Authorization ​

When a user logs in to your app and becomes authenticated, Privy issues the user an app access token. This token is signed by Privy and cannot be spoofed.

When your frontend makes a request to your backend, you should include the current user's access token in the request. This allows your server to determine whether the requesting user is truly authenticated or not.

Access token format ​

Privy access tokens are JSON Web Tokens (JWT), signed with the ES256 algorithm. These JWTs include certain information about the user in its claims, namely:

  • sid is the user’s current session ID
  • 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.

Authorizing requests with the access token ​

To include the current user's access token on requests to your backend, follow the instructions below. Make sure to follow the appropriate instructions depending on if your app uses local storage or cookies to store tokens.

You can get the current user's Privy token as a string using the getAccessToken method from the usePrivy hook. This method will also automatically refresh the user's access token if is nearing expiration or has expired.

tsx
const {getAccessToken} = usePrivy();
const accessToken = await getAccessToken();

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

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

tsx
const response = await fetch(<your-api-route>, {
    method: <your-request-method>
    body: <your-request-body>,
    headers: {
        'Authorization': `Bearer ${accessToken}`, 
        /* Add any other request headers you'd like */
    }
});

When a request is received by your backend, you should make sure to verify the user's access token to identify the user.

Getting the access token outside of React ​

If you need to get a user's Privy token outside of Privy's React context, you can directly import the getAccessToken method, instead of using the usePrivy hook, like below:

tsx
import {getAccessToken} from '@privy-io/react-auth';
...
const authToken = await getAccessToken();

Please note:

  • You should only import getAccessToken as above in special cases. Generally, this is only necessary if calling getAccessToken from a non-component file.
  • If you directly import the getAccessToken method, you must not invoke the method before PrivyProvider has rendered.

Whenever possible, you should retrieve getAccessToken from the usePrivy hook.

Managing expired access tokens ​

A user's access token might expire while they are actively using your app. For example, if a user does not take action on an application for an extended period of time, the access token can become expired.

In these scenarios, if a method returns with an 'invalid auth token' error, we recommend calling the getAccessToken method with a time-based backoff until the user's access token is refreshed with an updated expiration time.

If you receive an expired access token in your backend, return an error to your client, and as above, trigger getAccessToken in your client.

If the user's access token cannot be refreshed, the user will be logged out.