fastify-xauth-jwks
verifyJWT
Verify a JWT string against a path's JWKS. Returns the decoded payload or null on failure.
verifyJWT
Verify a JWT string against the JWKS configured for this path. On success returns the decoded payload object; on any failure (invalid signature, expired, missing sub) returns null and logs the error server-side.
Primarily useful for verifying tokens outside the normal request lifecycle — e.g., in webhook handlers, background jobs, or custom middleware.
Signature
fastify.xAuth.validators.<name>.verifyJWT(token: string): Promise<JWTPayload | null>
Params
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Raw JWT string (without the Bearer prefix). |
Returns
Promise<object | null> — The decoded JWT payload on success, or null if verification fails for any reason (invalid signature, expired, missing sub claim, non-string input).
Throws
Does not throw. All errors are caught internally, logged via fastify.log.error, and result in a null return value.
Examples
Basic — verify a token from a request header
fastify.post("/admin/webhook", async (request, reply) => {
const token = request.headers.authorization?.slice(7);
const payload = await fastify.xAuth.validators.admin.verifyJWT(token);
if (!payload) {
return reply.code(401).send({ error: "Invalid token" });
}
return { userId: payload.sub, scopes: payload.scopes };
});
Realistic — verify a token passed in a request body
fastify.post("/admin/impersonate", async (request, reply) => {
const { delegateToken } = request.body;
const delegatePayload = await fastify.xAuth.validators.admin.verifyJWT(delegateToken);
if (!delegatePayload) {
return reply.code(403).send({ error: "Invalid delegate token" });
}
if (!delegatePayload.roles?.includes("impersonator")) {
return reply.code(403).send({ error: "Not authorized to impersonate" });
}
return { impersonating: delegatePayload.sub };
});
See Also
- clearPayloadCache — Clear the in-memory payload cache for this path
- getPayloadCacheStats — Inspect cache size and TTL
AI Context
package: "@xenterprises/fastify-xauth-jwks"
method: fastify.xAuth.validators.<name>.verifyJWT(token)
use-when: Manually verify a JWT against a registered path's JWKS — returns payload or null (does not throw)
returns: decoded payload object | null