Middleware - Key0

Key0 provides access token validation middleware for every supported framework, plus a standalone validator for backend services that do not run the full SDK. All middleware functions extract the Bearer token from the Authorization header, verify it using the configured secret or public key, and attach the decoded payload to the request context. On failure they return a JSON error response and short-circuit the request.

Configuration Types

ValidateAccessTokenConfig

Used by the framework-specific middleware functions (validateAccessToken, honoValidateAccessToken, fastifyValidateAccessToken).

type ValidateAccessTokenConfig = {
  readonly secret: string;
};

Field	Type	Description
`secret`	`string`	HS256 shared secret. Must match the secret used by the `AccessTokenIssuer`.

ValidatorConfig

Used by the standalone validateKey0Token function. Supports both HS256 and RS256.

type ValidatorConfig = {
  secret?: string;
  publicKey?: string;
  algorithm?: "HS256" | "RS256";
};

Field	Type	Default	Description
`secret`	`string`	—	Shared secret for HS256. Required when `algorithm` is `"HS256"`.
`publicKey`	`string`	—	PEM-encoded public key for RS256. Required when `algorithm` is `"RS256"`.
`algorithm`	`"HS256" \| "RS256"`	`"HS256"`	Signing algorithm to expect.

AccessTokenPayload

All middleware functions resolve to the same decoded JWT payload shape.

type AccessTokenPayload = JWTPayload & {
  readonly sub: string;        // requestId
  readonly jti: string;        // challengeId
  readonly resourceId: string;
  readonly planId: string;
  readonly txHash: string;
};

Claim	Type	Description
`sub`	`string`	The `requestId` that initiated the payment flow.
`jti`	`string`	The `challengeId` assigned by the challenge engine.
`resourceId`	`string`	Identifier of the protected resource.
`planId`	`string`	The plan the client paid for.
`txHash`	`string`	On-chain transaction hash of the USDC payment.
`iat`	`number`	Issued-at timestamp (seconds since epoch).
`exp`	`number`	Expiration timestamp (seconds since epoch).

Framework Middleware

Express
Hono
Fastify
Standalone

validateAccessToken

Express middleware. On success, attaches the decoded payload to req.key0Token.

import { validateAccessToken } from "@key0ai/key0/express";

app.use(
  "/api/photos",
  validateAccessToken({ secret: process.env.ACCESS_TOKEN_SECRET }),
);

app.get("/api/photos", (req, res) => {
  const token = req.key0Token;
  res.json({ planId: token.planId, txHash: token.txHash });
});

Signature:

function validateAccessToken(
  config: ValidateAccessTokenConfig,
): (req: Request, res: Response, next: NextFunction) => Promise<void>;

Request property: req.key0Token (AccessTokenPayload)

honoValidateAccessToken

Hono middleware. On success, stores the decoded payload via c.set("key0Token", payload).

import { honoValidateAccessToken } from "@key0ai/key0/hono";

app.use("/api/photos/*", honoValidateAccessToken({
  secret: process.env.ACCESS_TOKEN_SECRET,
}));

app.get("/api/photos", (c) => {
  const token = c.get("key0Token");
  return c.json({ planId: token.planId, txHash: token.txHash });
});

Signature:

function honoValidateAccessToken(
  config: ValidateAccessTokenConfig,
): (c: Context, next: () => Promise<void>) => Promise<void | Response>;

Context value: c.get("key0Token") (AccessTokenPayload)

fastifyValidateAccessToken

Fastify onRequest hook. On success, attaches the decoded payload to request.key0Token.

import { fastifyValidateAccessToken } from "@key0ai/key0/fastify";

fastify.addHook(
  "onRequest",
  fastifyValidateAccessToken({
    secret: process.env.ACCESS_TOKEN_SECRET,
  }),
);

fastify.get("/api/photos", async (request, reply) => {
  const token = request.key0Token;
  return { planId: token.planId, txHash: token.txHash };
});

Signature:

function fastifyValidateAccessToken(
  config: ValidateAccessTokenConfig,
): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;

Request property: request.key0Token (AccessTokenPayload)

validateKey0Token

Lightweight validator for backend services. Does not require a blockchain connection or the full SDK. Supports both HS256 and RS256.

import { validateKey0Token } from "@key0ai/key0";

// HS256 (shared secret)
const payload = await validateKey0Token(
  req.headers.authorization,
  { secret: process.env.KEY0_SECRET },
);

// RS256 (public key)
const payload = await validateKey0Token(
  req.headers.authorization,
  {
    publicKey: process.env.KEY0_PUBLIC_KEY,
    algorithm: "RS256",
  },
);

Signature:

async function validateKey0Token(
  authHeader: string | null | undefined,
  config: ValidatorConfig,
): Promise<AccessTokenPayload>;

Throws a plain Error (not Key0Error) on failure. Error messages:

Message	Cause
`"Missing or malformed Authorization header"`	Header absent or missing `Bearer` prefix.
`"Token expired"`	The `exp` claim is in the past.
`"Invalid token signature"`	Signature verification failed.
`"Invalid token: missing claim <name>"`	A required claim (`sub`, `jti`, `resourceId`, `planId`, `txHash`) is missing.

Internal: validateToken

The framework-agnostic function used by validateAccessToken, honoValidateAccessToken, and fastifyValidateAccessToken. You do not need to call this directly unless you are building a custom integration.

import { validateToken } from "@key0ai/key0";

async function validateToken(
  authHeader: string | null | undefined,
  config: ValidateAccessTokenConfig,
): Promise<AccessTokenPayload>;

Throws Key0Error with the following codes:

Scenario	Error Code	HTTP Status
Missing or malformed `Authorization` header	`INVALID_REQUEST`	401
Token signature expired	`CHALLENGE_EXPIRED`	401
Invalid signature or malformed token	`INVALID_REQUEST`	401

Error Responses

All framework middleware functions return a consistent JSON error body on failure: 401 — Missing, expired, or invalid token:

{
  "type": "Error",
  "code": "INVALID_REQUEST",
  "message": "Missing or malformed Authorization header"
}

500 — Internal error (unexpected exception during verification):

{
  "type": "Error",
  "code": "INTERNAL_ERROR",
  "message": "Internal error"
}

Express Integration

Full setup guide for mounting Key0 routes and middleware in Express.

Backend Integration Example

Use validateKey0Token in a separate backend service.

AccessTokenIssuer

The JWT issuer whose tokens this middleware validates.

SDK Reference

​Configuration Types

​ValidateAccessTokenConfig

​ValidatorConfig

​AccessTokenPayload

​Framework Middleware

​validateAccessToken

​honoValidateAccessToken

​fastifyValidateAccessToken

​validateKey0Token

​Internal: validateToken

​Error Responses

​Related

Express Integration

Backend Integration Example

AccessTokenIssuer

Configuration Types

ValidateAccessTokenConfig

ValidatorConfig

AccessTokenPayload

Framework Middleware

validateAccessToken

honoValidateAccessToken

fastifyValidateAccessToken

validateKey0Token

Internal: validateToken

Error Responses

Related