@identsphere/verify

Verify IdentSphere access tokens locally in your backend — no per-request call to the auth server. It fetches the issuer's JWKS once (cached, with key-rotation + a refetch cooldown handled by jose) and verifies the RS256 JWT in-process. Works in Node, Deno, Bun, and Cloudflare Workers.

This is how you do backend auth at scale — exactly like validating an Auth0 or Clerk token: the hot path is local crypto, and you only ever call the auth server for the login/refresh flows.

npm install @identsphere/verify

Verify a token

import { createTokenVerifier } from "@identsphere/verify";

// Create ONCE per process and share it (the JWKS cache lives inside).
const verifier = createTokenVerifier({
  issuer: "https://auth.example.com",
  audience: "my-api", // optional; pair with the server's IDENTSPHERE_TOKEN_AUDIENCE
});

const claims = await verifier.verify(token); // throws TokenVerificationError on failure
// { sub, org, email, aal, iss, exp, ... } — no network hop

TokenVerificationError.reason is one of expired, invalid_signature, invalid_claims, malformed, jwks_unavailable.

Express / Connect middleware

import { requireAuth } from "@identsphere/verify/express";

app.use(requireAuth({ config: { issuer: "https://auth.example.com", audience: "my-api" } }));

app.get("/me", (req, res) => {
  res.json({ userId: req.identsphere.sub, org: req.identsphere.org });
});

req.identsphere carries the verified claims. A missing/invalid token ends the request with 401 (or 503 if the JWKS is unreachable). Pass required: false for optional auth (continues with req.identsphere undefined).

Config

| Option | Default | Purpose | | --- | --- | --- | | issuer | — | IdentSphere issuer URL; the token's iss must equal it. | | jwksUri | ${issuer}/.well-known/jwks.json | Override the JWKS location. | | audience | (unchecked) | Required aud; pair with IDENTSPHERE_TOKEN_AUDIENCE. | | cacheMaxAgeMs | 600000 | How long a fetched JWKS is reused. | | cooldownMs | 30000 | Min gap between unknown-kid refetches (flood throttle). | | clockToleranceSec | 5 | exp/nbf skew tolerance. |

License

BUSL-1.1 © Pradumna Gautam.