Backend wallet verification - Polygon Developer Docs

Verify a non-custodial wallet user on your backend by accepting an OMS Wallet ID token from the client and checking its ES256 signature and required claims against the configured token issuer.

An OIDC provider ID token is an input to wallet authentication. It is not the OMS Wallet ID token returned by getIdToken, and your backend must not verify it with the OMS Wallet issuer keys.

Start with the quickstart for your SDK first: TypeScript, React Native, Swift, or Kotlin.Kotlin snippets call suspend SDK APIs; run them from a coroutine.

During backend setup, inspect the iss and aud claims in an ID token returned by getIdToken from your own OMS project. Store those expected values as OMS_TOKEN_ISSUER and OMS_PROJECT_ID. Do not choose trusted values dynamically from a token received in an application request.

1. Send the OMS Wallet ID token to your backend

After the user authenticates in the app, request an ID token for the active wallet and pass it to your app’s backend client. That client sends the token to your backend over HTTPS.

TypeScript
React Native
Swift
Kotlin

const idToken = await omsWallet.wallet.getIdToken({
  ttlSeconds: 300,
})

const idToken = await omsWallet.wallet.getIdToken({
  ttlSeconds: 300,
})

let idToken = try await omsWallet.wallet.getIdToken(ttlSeconds: 300)

val idToken = omsWallet.wallet.getIdToken(ttlSeconds = 300u)

Send the returned string to your backend over HTTPS using your application’s backend client. Configure these backend environment variables:

Variable	Value
`OMS_TOKEN_ISSUER`	Exact `iss` value from a trusted setup token. The verifier also uses it as the JWKS base URL.
`OMS_PROJECT_ID`	Project ID in the trusted setup token’s `aud` claim.

2. Verify the token signature and claims

Fetch keys from the accepted issuer’s JWKS endpoint, and use a JWT library to verify the token. The library should select the signing key from the JWT header kid. The JWKS endpoint is:

{OMS_TOKEN_ISSUER}/.well-known/jwks.json

Validate:

Field	Expected value
JWT header `alg`	`ES256`
`iss`	Matches `OMS_TOKEN_ISSUER`
`aud`	Equals `OMS_PROJECT_ID` or is an array containing `OMS_PROJECT_ID`
`exp`	Is not in the past
`sub`	Non-empty wallet ID
`wallet_address`	EVM address for the wallet
`wallet_type`	Expected wallet type, such as `ethereum`

Install jose in the backend project that verifies the token:

pnpm add jose

Node.js

import {
  createLocalJWKSet,
  decodeJwt,
  errors,
  jwtVerify,
  type JSONWebKeySet,
  type JWTPayload,
} from 'jose'

function requiredEnv(name: string): string {
  const value = process.env[name]

  if (!value) {
    throw new Error(`Missing ${name}`)
  }

  return value
}

const EXPECTED_ISSUER = requiredEnv('OMS_TOKEN_ISSUER')
const EXPECTED_AUDIENCE = requiredEnv('OMS_PROJECT_ID')
const JWKS_CACHE_TTL_MS = 60 * 60 * 1000
const EVM_ADDRESS_PATTERN = /^0x[a-fA-F0-9]{40}$/

const jwksByIssuer = new Map<string, {
  jwks: ReturnType<typeof createLocalJWKSet>
  fetchedAt: number
}>()

function getTokenIssuer(idToken: string): string {
  const { iss } = decodeJwt(idToken)

  if (iss !== EXPECTED_ISSUER) {
    throw new Error('Unexpected token issuer')
  }

  return iss
}

async function getJwksForIssuer(
  issuer: string,
  options: { refresh?: boolean } = {},
) {
  const cached = jwksByIssuer.get(issuer)

  if (
    cached &&
    !options.refresh &&
    Date.now() - cached.fetchedAt < JWKS_CACHE_TTL_MS
  ) {
    return cached.jwks
  }

  const response = await fetch(new URL('/.well-known/jwks.json', issuer))

  if (!response.ok) {
    throw new Error('Failed to fetch issuer JWKS')
  }

  const jwksResponse = await response.json() as JSONWebKeySet
  const jwks = createLocalJWKSet(jwksResponse)
  jwksByIssuer.set(issuer, { jwks, fetchedAt: Date.now() })
  return jwks
}

type VerifiedWalletUser = {
  walletAddress: string
  walletType: 'ethereum'
  walletId: string
  email?: string
}

export async function verifyWalletIdToken(
  idToken: string,
): Promise<VerifiedWalletUser> {
  const issuer = getTokenIssuer(idToken)

  async function verifyWithJwks(refresh = false) {
    return jwtVerify(idToken, await getJwksForIssuer(issuer, { refresh }), {
      issuer,
      audience: EXPECTED_AUDIENCE,
      algorithms: ['ES256'],
      requiredClaims: ['exp'],
    })
  }

  let payload: JWTPayload

  try {
    const verified = await verifyWithJwks()
    payload = verified.payload
  } catch (error) {
    if (!(error instanceof errors.JWKSNoMatchingKey)) {
      throw error
    }

    const verified = await verifyWithJwks(true)
    payload = verified.payload
  }

  if (payload.wallet_type !== 'ethereum') {
    throw new Error('Unexpected wallet_type claim')
  }

  if (
    typeof payload.wallet_address !== 'string' ||
    !EVM_ADDRESS_PATTERN.test(payload.wallet_address)
  ) {
    throw new Error('Invalid wallet_address claim')
  }

  if (typeof payload.sub !== 'string' || payload.sub.length === 0) {
    throw new Error('Missing sub claim')
  }

  return {
    walletAddress: payload.wallet_address,
    walletType: payload.wallet_type,
    walletId: payload.sub,
    email: typeof payload.email === 'string' ? payload.email : undefined,
  }
}

3. Use the wallet claims

After verification succeeds, use only the OMS Wallet identity claims required for the current request. Treat custom claims as client-provided context unless your backend controls their values.

Claim	Description
`wallet_address`	User’s EVM wallet address.
`wallet_type`	Wallet type. Compare it with the type your application accepts.
`sub`	Wallet subject identifier. Use `wallet_address` for the EVM address.
`email`	User’s email address, when available.

Express

app.post('/api/wallet-session', async (req, res) => {
  const idToken = req.body.idToken

  if (typeof idToken !== 'string') {
    res.status(400).json({ error: 'Missing token' })
    return
  }

  try {
    const user = await verifyWalletIdToken(idToken)

    res.json({
      walletAddress: user.walletAddress,
      walletId: user.walletId,
      email: user.email ?? null,
    })
  } catch {
    res.status(401).json({ error: 'Invalid wallet token' })
  }
})

​1. Send the OMS Wallet ID token to your backend

​2. Verify the token signature and claims

​3. Use the wallet claims

1. Send the OMS Wallet ID token to your backend

2. Verify the token signature and claims

3. Use the wallet claims