Skip to main content

Web3Auth Identity Token

The Identity Token (ID Token) issued by Web3Auth is a JSON Web Token (JWT) that contains verified identity claims about the authenticated user. This token is signed using Web3Auth’s private key and cannot be spoofed, allowing developers to trust the identity information presented by the client.

Once a user successfully authenticates via Web3Auth, 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​

  • 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​

Web3Auth tokens are 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 Web3Auth Dashboard, personally identifiable information (PII) such as email, name, and profileImage will be omitted from the token.

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.

import { useIdentityToken } from "@web3auth/modal/react";

function IdentityTokenButton() {
  const { getIdentityToken, loading, error, token } = useIdentityToken();

  return (
    <div>
      <button onClick={() => getIdentityToken()} disabled={loading}>
        {loading ? "Authenticating..." : "Get Identity Token"}
      </button>
      {token && <div>Token: {token}</div>}
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

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 JWKS Endpoint​

JWKS Endpoint: https://api-auth.web3auth.io/.well-known/jwks.json

Example (Node.js with jose)
import * as jose from "jose";

const idToken = req.headers.authorization?.split(" ")[1];
const app_pub_key = req.body.appPubKey;

const jwks = jose.createRemoteJWKSet(new URL("https://api-auth.web3auth.io/.well-known/jwks.json"));
const jwtDecoded = await jose.jwtVerify(idToken, jwks, { algorithms: ["ES256"] });

// Verify wallet key match
if (
  jwtDecoded.payload.wallets.find((w) => w.type === "web3auth_app_key").public_key.toLowerCase() ===
  app_pub_key.toLowerCase()
) {
  res.status(200).json({ name: "Verification Successful" });
} else {
  res.status(400).json({ name: "Verification Failed" });
}

For External Wallets:​

if (
  jwtDecoded.payload.wallets.find((w) => w.type === "ethereum").address.toLowerCase() ===
  publicAddress.toLowerCase()
) {
  res.status(200).json({ name: "Verification Successful" });
} else {
  res.status(400).json({ name: "Verification Failed" });
}

Using Verification Key​

To manually verify the token, use your Verification Key available on the Project Settings page in the Web3Auth Dashboard.

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);
}
info

If the token is valid, the payload will contain identity claims (e.g., userId). If invalid, an error is thrown.

Things to Remember​

  • The iss field in the token must be https://api-auth.web3auth.io.
  • The aud field must match your Project Client ID.
  • The exp field must be in the future.
  • The iat field must be in the past.