Documentation

JWT Lab API

JWT Lab is intentionally not a complete OAuth authorization server. It is a test token mint: submit claims, receive a correctly signed RS256 JWT, and validate it against the published JWKS.

Issue a token

POST /api/token
Content-Type: application/json

{
  "preset": "delegated-agent",
  "claims": {
    "sub": "alice",
    "aud": "https://bank.example/mcp",
    "scope": "portfolio.read",
    "act": { "sub": "investment-advisor-agent" }
  },
  "expiresIn": 3600
}

Preset claims are applied first; explicit claims override them, and a claim set to null drops the preset default. The service manages iss, iat, exp and jti unless advanced: true is supplied.

Preset categories

Core — user and workload (client_credentials-shaped) access tokens. MCP — tokens audience-bound to an MCP server per the MCP authorization spec, with sub for the principal and client_id for the OAuth client. Delegation — RFC 8693 token-exchange output shapes with act chains: authorize on sub plus the outermost actor only.

Token profiles — spec-shaped tokens with their mandated typ headers set automatically:

basic-user           → typ: at+jwt            (RFC 9068 required: iss, exp, aud, sub, client_id, iat, jti)
spiffe-jwt-svid      → SPIFFE JWT-SVID        (sub is a SPIFFE ID; 5-minute lifetime; only sub, aud, exp required)
transaction-token    → typ: txntoken+jwt      (required: txn, sub, aud=trust domain, scope, req_wl)
id-jag               → typ: oauth-id-jag+jwt  (aud is the resource authorization server; client_id required)

Negative tests — validly signed tokens a conforming resource server must reject: expired and not-yet-valid (expect 401 invalid_token; introspection returns active: false). Other rejections (wrong iss, unbound aud, insufficient scope) are one claim edit away — set any claims you want in the payload. Edge cases — multi-valued aud arrays.

Discovery & validation

GET /.well-known/jwks.json
GET /.well-known/oauth-authorization-server
GET /.well-known/openid-configuration
GET /api/presets

Introspect a token

POST /api/introspect
Content-Type: application/x-www-form-urlencoded

token=eyJhbGciOiJSUzI1NiIs...

{"active": true, "sub": "alice", "exp": 1767225600, ...}

RFC 7662 token introspection: JWT Lab verifies the signature (RS256 against its published JWKS) and exp/nbf itself and returns an OAuth introspection response. Invalid, expired, tampered or malformed tokens return {"active": false} with no claim echo. The endpoint is unauthenticated: tokens are public-key-signed JWTs anyone holding them can decode, so introspection adds only the issuer's live validity opinion. Because JWT Lab is stateless, it can never report a valid token as revoked.

Token exchange (RFC 8693)

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&subject_token=<JWT>
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt
&actor_token=<JWT>
&actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt
&audience=https%3A%2F%2Fapi.example.com
&scope=profile.read

A spec-shaped token exchange: the subject token's claims are embedded in the issued JWT, and the actor token's claims become the act claim. Clients authenticate with any client_id/client_secret (HTTP Basic or form params) — credentials are accepted but never validated, and client_id is stamped into the token as a top-level claim.

Deliberate lab behavior:

Inbound tokens are decoded, never validated. Signature, expiry and issuer are not checked — the tokens are embedded inputs, not proofs. A subject token with no sub claim is rejected with invalid_request.

Delegation chains compose. If the subject token carries an act claim, it nests beneath the new outermost actor per RFC 8693 Figure 6, so history is preserved. Claims inside act are the actor's identity claims; exp/nbf/aud are stripped there per §4.1. With no actor_token, the exchanging client is treated as the acting party: its client_id becomes act.sub (the subject token's own chain, if any, nests beneath).

Request params win. audience and resource (repeatable) override the embedded aud; scope overrides the embedded scope. Omitted, the embedded values carry over; with neither, aud is left off. A resource that is not an absolute URI or carries a fragment is rejected with invalid_target.

Fixed lifetime. iss, iat, exp (JWT_DEFAULT_TTL, default 3600s) and jti are stamped by the lab; the inbound tokens' claims never drive the output expiry.

Errors are OAuth error codes: invalid_request for malformed requests and undecodable tokens, unsupported_grant_type for any grant other than the exchange URN, invalid_target for malformed resources. Every request is logged to the server output as one JSON line — form parameters, raw inbound tokens, their decoded claims and the outcome — with client_secret and the Authorization header masked. If your tokens carry sensitive claims, remember they will appear in the logs.

MCP

Connect an MCP client to <your-lab-host>/mcp. The remote server exposes five tools:

issue_token
introspect_token
list_presets
get_jwks
get_oauth_metadata

The MCP interface uses the same issuance engine as the UI and REST API, so an agent can mint a token and immediately inject it into whatever integration it is testing.

Hosting setup

JWT Lab is host-agnostic: it runs on any Node environment (serverless, container or plain process). Configure the environment before serving traffic:

npm install
npm run generate:key

# Set the printed JWT_PRIVATE_KEY_B64 value in the hosting environment.
# Also set:
JWT_ISSUER=https://your-lab.example.com
JWT_KID=jwt-lab-rs256-1

Important: keep the signing key stable. If an instance generates a different key, a token minted by one invocation might not validate against JWKS served by another.