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 IDsub
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.
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 callinggetAccessToken
from a non-component file. - If you directly import the
getAccessToken
method, you must not invoke the method beforePrivyProvider
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.