Access tokens

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.

Looking to access user data? Check out our Identity tokens.

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 their claims, namely:

Show properties

sid

string

The user’s current session ID

sub

string

The user’s Privy DID

iss

string

The token issuer, which should always be privy.io

aud

string

Your Privy app ID

iat

number

The timestamp of when the JWT was issued

exp

number

The timestamp of when the JWT will expire and is no longer valid. This is generally 1 hour after the JWT was issued.

Read more about Privy’s tokens and their security in our security guide.

Sending the access token

Accessing the token from your client

To include the current user’s access token in requests from your frontend to your backend, you’ll first need to retrieve it, then send it appropriately.

If your app is configured to use HTTP-only cookies (instead of the default local storage), the access token will automatically be included in the cookies for requests to the same domain. In this case, you don’t need to manually include the token in the request headers.

Using the access token with popular libraries

When sending requests to your backend, here’s how you can include the access token with different HTTP client libraries:

fetch
axios
ofetch

// For bearer token approach (when using local storage)
const accessToken = await getAccessToken();
const response = await fetch('<your-api-endpoint>', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
});

// For HTTP-only cookies approach
const response = await fetch('<your-api-endpoint>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  credentials: 'include', // This includes cookies automatically
  body: JSON.stringify(data)
});

import axios from 'axios';

// For bearer token approach (when using local storage)
const accessToken = await getAccessToken();
const response = await axios({
  method: 'post',
  url: '<your-api-endpoint>',
  headers: {
    Authorization: `Bearer ${accessToken}`
  },
  data: data
});

// For HTTP-only cookies approach
const response = await axios({
  method: 'post',
  url: '<your-api-endpoint>',
  withCredentials: true, // This includes cookies automatically
  data: data
});

import {ofetch} from 'ofetch';

// For bearer token approach (when using local storage)
const accessToken = await getAccessToken();
const response = await ofetch('<your-api-endpoint>', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`
  },
  body: data
});

// For HTTP-only cookies approach
const response = await ofetch('<your-api-endpoint>', {
  method: 'POST',
  credentials: 'include', // This includes cookies automatically
  body: data
});

Getting the access token

Accessing the token from your server

When your server receives a request, the location of the user’s access token depends on whether your app uses local storage (the default) or cookies to manage user sessions.

Show local storage setup

If you’re using local storage for session management, the access token will be passed in the Authorization header of the request with the Bearer prefix. You can extract it like this:

NodeJS
Go
Python

// Example for Express.js
const accessToken = req.headers.authorization?.replace('Bearer ', '');

// Example for Next.js API route
const accessToken = req.headers.authorization?.replace('Bearer ', '');

// Example for Next.js App Router
const accessToken = headers().get('authorization')?.replace('Bearer ', '');

// Example for Go
accessToken := r.Header.Get("Authorization")
accessToken = strings.Replace(accessToken, "Bearer ", "", 1)

# Example for Python
accessToken = request.headers.get("Authorization")
accessToken = accessToken.replace("Bearer ", "")

Show cookie setup

If you’re using HTTP-only cookies for session management, the access token will be automatically included in the privy-token cookie. You can extract it like this:

NodeJS
Go
Python

// Example for Express.js
const accessToken = req.cookies['privy-token'];

// Example for Next.js API route
const accessToken = req.cookies['privy-token'];

// Example for Next.js App Router
const cookieStore = cookies();
const accessToken = cookieStore.get('privy-token')?.value;

// Example for Go
accessToken := r.Cookies["privy-token"]

# Example for Python
accessToken = request.cookies.get("privy-token")

Verifying the access token

Once you’ve obtained the user’s access token from a request, you should verify the token against Privy’s verification key for your app to confirm that the token was issued by Privy and the user referenced by the DID in the token is truly authenticated. The access token is a standard ES256 JWT and the verification key is a standard Ed25519 public key. You can verify the access token against the public key using the @privy-io/node or @privy-io/server-auth libraries or using a third-party library for managing tokens.

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.

Handle invalid token errors: 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.
Return errors from backend: If you receive an expired access token in your backend, return an error to your client, and as above, trigger getAccessToken in your client.
Handle failed refreshes: If the user’s access token cannot be refreshed, the user will be logged out.

Using Privy authentication

Using your own authentication

Access token format

Sending the access token

Accessing the token from your client

Using the access token with popular libraries

Getting the access token

Accessing the token from your server

Verifying the access token

Managing expired access tokens

Using Privy authentication

Using your own authentication

​Access token format

​Sending the access token

​Accessing the token from your client

​Using the access token with popular libraries

​Getting the access token

​Accessing the token from your server

​Verifying the access token

​Managing expired access tokens

Access token format

Sending the access token

Accessing the token from your client

Using the access token with popular libraries

Getting the access token

Accessing the token from your server

Verifying the access token

Managing expired access tokens