ChitmarkDocs
llms.txtHomePublic beta

API reference

JWKS

GET/.well-known/jwks.json

JWKS for verdictToken verification

Public key set used to verify ES256 verdictToken JWTs issued by verify. No authentication required.

After signature verification, require iss === "https://api.chitmark.com", match tid to the expected tenant, and match sub to the expected session before authorizing.

Response

keysJWK[]optional

EC P-256 public JWKs for ES256 (kty/crv/alg/use/kid/x/y). Empty until configured: fail closed. Require JWT alg === "ES256" before verify (wrong_algorithm); never trust the token-requested alg.

Notes

  • Claim set and binding rules: see VerdictTokenClaims in the OpenAPI contract and the Verdict tokens guide.
  • Algorithm: each key is an EC P-256 public JWK for ES256. Require JWT header alg === "ES256" before verifying (reject wrong_algorithm); never select whatever algorithm the token requests. Flow: JWT alg = ES256 → JWKS key compatible with ES256 → signature verification.
  • Empty JWKS: { "keys": [] } means no verdict token can currently be cryptographically verified. Consumers must fail closed; never treat an empty key set as evidence that a token is valid. Local/CI without a signing key may also emit unsigned.<eventId> placeholders; SDK helpers reject those.
  • kid is required on every signed JWT (fingerprint of the public key). Token TTL is 5 minutes. Rotation contract: introduce the new key while the old remains published (overlap), then remove the old key only after tokens under it expire (keep ≥ 5 minutes + 60 seconds JWKS cache skew). Previously issued tokens remain verifiable for their full lifetime when this contract is followed.
  • HTTP caching: responses include Cache-Control: public, max-age=60 and a strong ETag. Respect Cache-Control; when ETag or Last-Modified are present, use conditional requests (If-None-Match / If-Modified-Since) instead of a hard-coded refresh interval (304 when unchanged). Still refresh immediately on an unknown kid. Do not fetch on every verification, and never permanently pin a single signing key. Never disable signature verification because JWKS is temporarily unavailable: fail closed (jwks_unavailable / unknown_kid), never allow.
Request
curl -s https://api.chitmark.com/.well-known/jwks.json
Response
{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "…",
      "y": "…",
      "kid": "…",
      "alg": "ES256",
      "use": "sig"
    }
  ]
}