Authentication - Numpay Docs

Protected endpoints require a Web3Auth ID token for the Numpay app in the Authorization header:

Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...

Getting a token

In the browser, after a Web3Auth login:

import { useWeb3Auth } from '@web3auth/modal/react';

const { web3Auth } = useWeb3Auth();
const { idToken } = await web3Auth.getUserInfo();

await fetch('https://api.numpay.app/api/user/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${idToken}`,
  },
  body: JSON.stringify({ walletAddress }),
});

How the server verifies it

Check	Expected value
Signature	Valid against `https://api-auth.web3auth.io/jwks`
Algorithm	`ES256`
Issuer (`iss`)	`https://api-auth.web3auth.io`
Audience (`aud`)	Numpay’s Web3Auth client ID
Identity claim	`userId` (or legacy `verifierId`) present

The identity claim is the verified phone number for SMS logins or the email address for email logins. The server tells them apart by the presence of @.

Lifetime

Tokens are tied to the Web3Auth session, which lasts up to one day. After it expires, the API returns 401 and the client must log in again.

Errors

Status	Body	Cause
`401`	`{ "error": "Authentication required", "message": "Bearer token is required" }`	No `Authorization: Bearer` header
`401`	`{ "error": "Authentication failed", "message": "Invalid or expired token" }`	Bad signature, wrong audience, expired, or no identity claim