​
Overview

Privy supports all JWT-based authentication providers. This includes any OIDC compliant authentication system, including OAuth 2.0, Auth0, Firebase, AWS Cognito, and more.

Using JWT-based authentication integration, you can use your existing authentication system with Privy’s services. This approach allows users to maintain their existing login experience while giving them access to embedded wallets.

Privy’s authentication is fully compatible with any authentication provider that supports JWT-based, stateless authentication. When a user logs into your app, your auth provider issues them an access and/or identity token to represent their auth status. Privy validates this token to authenticate your user.

​
Setting up JWT-based authentication

To integrate your JWT-based auth provider with Privy:

  1. Go to the Privy Dashboard
  2. Select your app from the App Dropdown in the left sidebar
  3. Request access to Custom Auth Support in the Integrations > Plugins tab of the Privy dashboard
  4. Navigate to the JWT Dashboard via User management > Authentication > JWT-based auth

You’ll need to provide the following information:

​
JWT Verification Details
required

Privy requires a verification key to ensure the JWTs received are valid. Both the token’s signature and its expiration time (claim) are verified to ensure secure access. This verification process helps protect user data and prevents unauthorized access to Privy services.

You can provide the verification key in one of two ways:

​
JWT ID Claim
default:"sub"

Enter the claim from your user’s JWT that contains the user’s unique ID. In most access tokens and identity tokens, this is the claim.

​
Usage

​
Implementation

To integrate JWT-based authentication with Privy in your React application, you’ll need to create a custom PrivyProvider wrapper that supplies your auth token to Privy.

​
Create a custom PrivyProvider wrapper

Create a component that wraps the PrivyProvider with your custom auth configuration:

PrivyAuthProvider.tsx
import { useCallback, PropsWithChildren } from 'react';
import { PrivyProvider } from '@privy-io/react-auth';

// Import your auth provider's hook or state management
import { useAuth } from 'your-auth-provider';

const PrivyAuthProvider: React.FC<PropsWithChildren> = ({ children }) => {
// Get auth details from your provider
const { getToken, isLoading, isAuthenticated } = useAuth();

// Create a callback to get the token
const getCustomToken = useCallback(
    async () => {
        // Your logic to retrieve the JWT token from your auth provider
        try {
            const token = await getToken();
            return token;
        } catch (error) {
            // If there's an error, the user is likely not authenticated
            return undefined;
        }
    },
    [isAuthenticated, getToken], // Re-create when auth state changes
);

return (
    <PrivyProvider
        appId='your-privy-app-id'
        config={{
            customAuth: {
                // Indicates if your auth provider is currently updating auth state
                isLoading: isLoading,
                // Callback to get the user's JWT token
                getCustomAccessToken: getCustomToken,
            },
        }}
    >
        {children}
    </PrivyProvider>
    );
};

export default PrivyAuthProvider;

​
Integrate the provider with your app

Make sure to nest your custom provider inside your auth provider in your app structure:

App.tsx
import { AuthProvider } from 'your-auth-provider';
import PrivyAuthProvider from './PrivyAuthProvider';

function App() {
return (
    <AuthProvider>
    {/* Our custom wrapper must be nested inside your AuthProvider */}
    <PrivyAuthProvider>
        {/* Your app content */}
        <MainContent />
    </PrivyAuthProvider>
    </AuthProvider>
);
}

export default App;

​
Accessing User Authentication Status

Once configured, you can access the user’s authentication status through the Privy SDK:

import { usePrivy } from '@privy-io/react-auth';

function MainContent() {
const { user, ready, authenticated } = usePrivy();

if (!ready) {
    return <div>Loading...</div>;
}

if (!authenticated) {
    return <div>Please log in through your authentication provider</div>;
}

return (
    <div>
    <p>Welcome, authenticated user!</p>
    <p>User ID: {user.id}</p>
    </div>
);
}

When using a custom authentication provider, you should not use the Privy login method (from useLogin or usePrivy). Instead, call the login method of your custom provider, and the Privy SDK will automatically synchronize its state.