custom-jwt-example

MetaMask Embedded Wallets — Custom JWT

React + Vite example using MetaMask Embedded Wallets (powered by Web3Auth) with a bring-your-own JWT backend. You issue the JWT from your own server; Web3Auth validates it via your JWKS endpoint and derives the user's wallet. Compatible with any OAuth 2.0 / OIDC-compliant identity provider.

The JWT must include an iat claim within 60 seconds of the current time on every login attempt, regardless of exp.

Prerequisites

• Node.js 20+
• npm
• A Client ID from the Dashboard
• Your own JWT issuer with a publicly accessible JWKS endpoint
• A custom JWT connection configured on the Dashboard (Custom JWT guide)

Setup

1. Clone the repository

git clone https://github.com/Web3Auth/web3auth-examples.git
cd web3auth-examples/custom-authentication/single-connection/custom-jwt-example

2. Install dependencies

npm install

3. Start the JWT issuer (required)

In a separate terminal, start the demo JWT server:

cd server
npm install
npm start

The server runs at http://localhost:8080 by default and exposes /api/token.

4. Configure environment variables

cp .env.example .env

Edit .env:

VITE_WEB3AUTH_CLIENT_ID=YOUR_CLIENT_ID

Optional — override the JWT server URL (defaults to http://localhost:8080):

VITE_JWT_SERVER_URL=http://localhost:8080

5. Run the application

npm run dev

Visit http://localhost:5173 in your browser.

Resources

• MetaMask Embedded Wallets Documentation
• Build with AI — set up the MCP server and skill for AI-assisted integration
• Custom JWT Guide
• Dashboard
• Community — Builder Hub

License

MIT