AccessTokenIssuer

AccessTokenIssuer handles JWT creation and verification for the Key0 payment flow. After a client completes an on-chain USDC payment, the engine uses AccessTokenIssuer to mint a signed JWT that grants access to the purchased resource. It supports two signing algorithms:

HS256 — symmetric shared secret (default). Suitable for single-service deployments.
RS256 — asymmetric RSA key pair. Suitable for distributed systems where multiple services verify tokens using the public key.

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

Constructor

const issuer = new AccessTokenIssuer("your-secret-at-least-32-characters-long");

const issuer = new AccessTokenIssuer({
  secret: "your-secret-at-least-32-characters-long",
  algorithm: "HS256",
});

const issuer = new AccessTokenIssuer({
  privateKey: process.env.RSA_PRIVATE_KEY, // PEM format
  algorithm: "RS256",
});

Parameters

AccessTokenIssuerConfig | string

required

Either a plain string (interpreted as an HS256 shared secret) or a configuration object.

AccessTokenIssuerConfig

Property	Type	Required	Description
`secret`	`string`	When using HS256	Shared secret. Must be at least 32 characters.
`privateKey`	`string`	When using RS256	RSA private key in PEM (PKCS#8) format.
`algorithm`	`"HS256" \| "RS256"`	No	Signing algorithm. Defaults to `"HS256"`.

Validation

The constructor throws immediately if:

An HS256 secret is shorter than 32 characters.
RS256 is selected but no privateKey is provided.
HS256 is selected (or defaulted) but no secret is provided.

Methods

sign

Signs a JWT containing the provided claims.

sign(claims: TokenClaims, ttlSeconds: number): Promise<TokenResult>

TokenClaims

required

The claims to embed in the JWT payload. See TokenClaims below.

number

required

Token time-to-live in seconds. The exp claim is set to iat + ttlSeconds.

string

The signed JWT string.

Returns Promise<TokenResult> — an object with a single token property.

verify

Verifies a JWT signed with HS256 and returns the decoded payload.

verify(token: string): Promise<TokenClaims & { iat: number; exp: number }>

string

required

The JWT string to verify.

Returns the decoded payload including standard iat and exp claims.

This method only supports HS256. Calling verify on an RS256 issuer throws an error. For RS256 token verification, use validateKey0Token from the middleware layer, which accepts a public key.

verifyWithFallback

Attempts verification with the primary secret first, then iterates through fallback secrets. Designed for zero-downtime secret rotation.

verifyWithFallback(
  token: string,
  fallbackSecrets: string[]
): Promise<TokenClaims & { iat: number; exp: number }>

string

required

The JWT string to verify.

string[]

required

An ordered list of previous secrets to try if the primary secret fails.

Returns the decoded payload if any secret succeeds. Throws "Token verification failed with all secrets" if the primary and all fallback secrets fail.

Types

TokenClaims

Claims embedded in every Key0 access token.

Claim	Type	Description
`sub`	`string`	The `requestId` that initiated the payment flow.
`jti`	`string`	The `challengeId` (used for replay prevention).
`resourceId`	`string`	Identifier of the purchased resource.
`planId`	`string`	Identifier of the purchased plan.
`txHash`	`string`	On-chain USDC transaction hash that funded the access.

Standard JWT claims iat (issued at) and exp (expiration) are set automatically by sign and included in the return type of verify and verifyWithFallback.

TokenResult

type TokenResult = {
  readonly token: string;
};

Usage

Signing and verifying a token

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

const issuer = new AccessTokenIssuer("a-secret-that-is-at-least-32-characters");

// Sign a token after successful payment
const { token } = await issuer.sign(
  {
    sub: "req_abc123",
    jti: "ch_xyz789",
    resourceId: "weather-api",
    planId: "plan_basic",
    txHash: "0x1234...abcd",
  },
  3600, // 1 hour TTL
);

// Verify the token on a subsequent request
const claims = await issuer.verify(token);
console.log(claims.resourceId); // "weather-api"
console.log(claims.exp);        // Unix timestamp

Zero-downtime secret rotation

When rotating secrets, pass the old secret(s) as fallbacks so that tokens signed with the previous secret remain valid until they expire.

const currentSecret = process.env.ACCESS_TOKEN_SECRET!;
const previousSecrets = [process.env.ACCESS_TOKEN_SECRET_OLD!];

const issuer = new AccessTokenIssuer(currentSecret);

// New tokens are signed with currentSecret
const { token } = await issuer.sign(claims, 3600);

// Verification accepts tokens signed with either secret
const decoded = await issuer.verifyWithFallback(token, previousSecrets);

RS256 signing

const issuer = new AccessTokenIssuer({
  privateKey: process.env.RSA_PRIVATE_KEY!,
  algorithm: "RS256",
});

const { token } = await issuer.sign(claims, 3600);
// Distribute the corresponding public key to verifying services

Token Issuance

Security design behind JWT creation, claims, and verification.

Middleware

Framework middleware that validates tokens issued by AccessTokenIssuer.

​Constructor

​Parameters

​AccessTokenIssuerConfig

​Validation

​Methods

​sign

​verify

​verifyWithFallback

​Types

​TokenClaims

​TokenResult

​Usage

​Signing and verifying a token

​Zero-downtime secret rotation

​RS256 signing

​Related

Token Issuance

Middleware

Constructor

Parameters

AccessTokenIssuerConfig

Validation

Methods

sign

verify

verifyWithFallback

Types

TokenClaims

TokenResult

Usage

Signing and verifying a token

Zero-downtime secret rotation

RS256 signing

Related