> For the complete documentation index, see [llms.txt](/llms.txt). # Embedded Wallets identity token The **Identity Token** (ID Token) issued by Embedded Wallets is a JSON Web Token (JWT) that contains verified identity claims about the authenticated user. This token is signed using Embedded Wallets' private key and cannot be spoofed, allowing developers to trust the identity information presented by the client. Once a user successfully authenticates via Embedded Wallets, the platform issues an ID token which can then be used to authorize client-to-server requests or verify ownership of associated wallet addresses. #### Purpose of the ID token[](#purpose-of-the-id-token "Direct link to Purpose of the ID token") - **User identity verification**: Ensures that the client user is indeed who they claim to be. - **Secure backend requests**: The token should be passed in API requests to validate sessions server-side. - **Wallet ownership proof**: Includes public wallet keys to prove a user owns a particular wallet. When making a backend request from the frontend, the client must include this ID token to ensure the backend can verify the authenticated user. ## ID token format[](#id-token-format "Direct link to ID token format") Embedded Wallets (previously Web3Auth) issues tokens as ES256-signed JWTs containing various identity claims about the user. A sample decoded token is shown below:

Sample ID Token

{
  "iat": 1747727490,
  "aud": "BJp5VGbuhg_mUA.....7B0SseDPBWabmYmEFXpfu8CGWSw",
  "nonce": "030cb3f1ab9593d987b17cb....38afe331561105213",
  "iss": "https://api-auth.web3auth.io",
  "wallets": [
    {
      "public_key": "5771379329ae0f3b76........82f17373a13d8683561",
      "type": "web3auth_app_key",
      "curve": "ed25519"
    },
    {
      "public_key": "020fda199e933b24a74...........6c9cc67a13c23d",
      "type": "web3auth_app_key",
      "curve": "secp256k1"
    }
  ],
  "email": "shahbaz@web3auth.io",
  "name": "Mohammad Shahbaz Alam",
  "profileImage": "https://lh3.googleusercontent.com/a/AcJD_Fs0...._xzcWYzT=s96-c",
  "authConnection": "web3auth",
  "userId": "shahbaz@web3auth.io",
  "groupedAuthConnectionId": "web3auth-google-sapphire-mainnet",
  "exp": 1747813890
}

NOTE

If the Return user data in identity token setting is disabled on the dashboard, personally identifiable information (PII) such as email, name, and profileImage will be omitted from the token.

## Getting the ID Token[](#getting-the-id-token "Direct link to Getting the ID Token") To retrieve the ID token on the client-side, use the `getIdentityToken()` method. This is typically called after the user logs in. - React SDK - Vue SDK - JavaScript SDK ``` import { useIdentityToken } from '@web3auth/modal/react' function IdentityTokenButton() { const { getIdentityToken, loading, error, token } = useIdentityToken() return (

{token &&

Token: {token}

} {error &&

Error: {error.message}

}

) } ``` ``` ``` ``` try { const idToken = await web3auth.getIdentityToken() console.log(idToken) } catch (error) { console.error('Error authenticating user:', error) } ``` ## Verifying the ID Token[](#verifying-the-id-token "Direct link to Verifying the ID Token") To validate an ID token server-side, use Web3Auth's JWKS endpoint or project-specific verification key. This process ensures the JWT was issued by Web3Auth and its contents have not been tampered with. ### Using the JWKS endpoint[](#using-the-jwks-endpoint "Direct link to Using the JWKS endpoint") Always validate `issuer` and `audience` Every JWKS-based verification call **must** include both `issuer` and `audience` options: - **`audience`** must equal your **Project Client ID**. Without it, a token issued by Web3Auth for any other project will pass signature verification — because all projects share the same signing infrastructure. - **`issuer`** must match the Web3Auth endpoint that issued the token (`https://api-auth.web3auth.io` for social logins, `https://authjs.web3auth.io` for external wallets). **Who is at risk without `audience` validation?** | User identifier used by dapp | Exploitable without aud? | Reason | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ | | userId / email / authConnectionId | **Yes** | These claims are set by verifier configuration, which an attacker controls via their own project | | wallets[].public_key (app-scoped key) | No | App keys are derived per-project; a different project produces different keys | | wallets[].address (onchain address) | No | Bound to the user's cryptographic keys, cannot be forged | If your backend matches users by `userId`, `email`, or `authConnectionId` — the common pattern for Web2-style user management — always validate `audience`. - Social Login - External Wallets - Frontend Call JWKS Endpoint: `https://api-auth.web3auth.io/jwks` login/route.ts ``` import * as jose from 'jose' import { NextRequest, NextResponse } from 'next/server' export async function POST(req: NextRequest) { try { // Extract JWT token from Authorization header const authHeader = req.headers.get('authorization') const idToken = authHeader?.split(' ')[1] // Get public key from request body const { appPubKey } = await req.json() if (!idToken) { return NextResponse.json({ error: 'No token provided' }, { status: 401 }) } if (!appPubKey) { return NextResponse.json({ error: 'No appPubKey provided' }, { status: 400 }) } // Verify JWT using Web3Auth JWKS const jwks = jose.createRemoteJWKSet(new URL('https://api-auth.web3auth.io/jwks')) const { payload } = await jose.jwtVerify(idToken, jwks, { algorithms: ['ES256'], issuer: 'https://api-auth.web3auth.io', audience: process.env.WEB3AUTH_CLIENT_ID, }) // Find matching wallet in JWT const wallets = (payload as any).wallets || [] const normalizedAppKey = appPubKey.toLowerCase().replace(/^0x/, '') const isValid = wallets.some((wallet: any) => { if (wallet.type !== 'web3auth_app_key') return false const walletKey = wallet.public_key.toLowerCase() // Direct key comparison for ed25519 keys if (walletKey === normalizedAppKey) return true // Handle compressed secp256k1 keys if ( wallet.curve === 'secp256k1' && walletKey.length === 66 && normalizedAppKey.length === 128 ) { const compressedWithoutPrefix = walletKey.substring(2) return normalizedAppKey.startsWith(compressedWithoutPrefix) } return false }) if (isValid) { return NextResponse.json({ name: 'Verification Successful' }, { status: 200 }) } else { return NextResponse.json({ name: 'Verification Failed' }, { status: 400 }) } } catch (error) { console.error('Social login verification error:', error) return NextResponse.json({ error: 'Verification error' }, { status: 500 }) } } ``` JWKS Endpoint: `https://authjs.web3auth.io/jwks` login-external/route.ts ``` import * as jose from 'jose' import { NextRequest, NextResponse } from 'next/server' export async function POST(req: NextRequest) { try { // Extract JWT token from Authorization header const authHeader = req.headers.get('authorization') const idToken = authHeader?.split(' ')[1] // Get address from request body const { address } = await req.json() if (!idToken) { return NextResponse.json({ error: 'No token provided' }, { status: 401 }) } if (!address) { return NextResponse.json({ error: 'No address provided' }, { status: 400 }) } // Verify JWT using AuthJS JWKS const jwks = jose.createRemoteJWKSet(new URL('https://authjs.web3auth.io/jwks')) const { payload } = await jose.jwtVerify(idToken, jwks, { algorithms: ['ES256'], issuer: 'https://authjs.web3auth.io', audience: process.env.WEB3AUTH_CLIENT_ID, }) // Find matching wallet in JWT const wallets = (payload as any).wallets || [] const addressToCheck = Array.isArray(address) ? address[0] : address const normalizedAddress = addressToCheck.toLowerCase() const isValid = wallets.some((wallet: any) => { return ( wallet.type === 'ethereum' && wallet.address && wallet.address.toLowerCase() === normalizedAddress ) }) if (isValid) { return NextResponse.json({ name: 'Verification Successful' }, { status: 200 }) } else { return NextResponse.json({ name: 'Verification Failed' }, { status: 400 }) } } catch (error) { console.error('External wallet verification error:', error) return NextResponse.json({ error: 'Verification error' }, { status: 500 }) } } ``` App.tsx ``` const { token, getIdentityToken, loading: idTokenLoading, error: idTokenError } = useIdentityToken() const validateIdToken = async () => { const idToken = await getIdentityToken() let res if (connectorName === 'auth') { // Social login: send public key const pubKey = await web3Auth?.provider?.request({ method: 'public_key' }) console.log('pubKey:', pubKey) res = await fetch('/api/login', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${idToken}`, }, body: JSON.stringify({ appPubKey: pubKey }), }) } else { // External wallet: send address const address = await web3Auth?.provider?.request({ method: 'eth_accounts' }) res = await fetch('/api/login-external', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${idToken}`, }, body: JSON.stringify({ address }), }) } // Handle response if (res.status === 200) { toast.success('JWT Verification Successful') uiConsole(`Logged in Successfully!`, userInfo) } else { toast.error('JWT Verification Failed') await disconnect() } return res.status } ``` ### Using the verification key[](#using-the-verification-key "Direct link to Using the verification key") To manually verify the token, use your **Verification Key** available on the **Project Settings** page in the dashboard. - jose - jsonwebtoken ``` npm install jose ``` Example (JWT Verification using jose) ``` const verificationKey = await jose.importSPKI('insert-your-web3auth-verification-key', 'ES256') const idToken = 'insert-the-users-id-token' try { const payload = await jose.jwtVerify(idToken, verificationKey, { issuer: 'https://api-auth.web3auth.io', audience: 'your-project-client-id', }) console.log(payload) } catch (error) { console.error(error) } ``` ``` npm install jsonwebtoken ``` Example (JWT Verification using jsonwebtoken) ``` const verificationKey = 'insert-your-web3auth-verification-key'.replace(/\\n/g, '\n') const idToken = 'insert-the-users-id-token' try { const decoded = jwt.verify(idToken, verificationKey, { issuer: 'https://api-auth.web3auth.io', audience: 'your-project-client-id', }) console.log(decoded) } catch (error) { console.error(error) } ``` note The replace operation above ensures that any instances of '\n' in the stringified public key are replaced with actual newlines, per the PEM-encoded format. info If the token is valid, the payload will contain identity claims (such as, userId). If invalid, an error is thrown. ## Troubleshooting[](#troubleshooting "Direct link to Troubleshooting") - Validate that `iss` equals `https://api-auth.web3auth.io` (social logins) or `https://authjs.web3auth.io` (external wallets). A mismatch means the token was not issued by the expected Web3Auth service. - Validate that `aud` equals your **Project Client ID**. A mismatch means the token was issued for a different project and must be rejected. - Validate that `exp` is in the future. Expired tokens must be rejected. - Validate that `iat` is in the past. A future `iat` indicates a malformed or tampered token.