Public JWKS

Endpoints

• JWKS (recommended): https://api.cloakapi.io/api/.well-known/cloakapi-receipt-pubkeys.jwks
• PEM (legacy): https://api.cloakapi.io/api/.well-known/cloakapi-receipt-pubkey.pem

The JWKS is a standard RFC 7517 JSON Web Key Set:

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "kid": "gw-prod-2026-q2",
      "x":   "BASE64URL_X",
      "y":   "BASE64URL_Y",
      "use": "sig",
      "alg": "ES256",
      "x-cloakapi-active": true
    }
  ]
}

Key rotation

• Keys are named after the quarter they were issued in (gw-prod-2026-q2). A key stays active until it is rotated, which can be later than the end of that quarter — the name is not an expiry date.
• A new key signs receipts immediately; the old key stays in the JWKS indefinitely (marked x-cloakapi-active: false) so historic receipts continue to verify. Routine rotation never sets revoked.
• Compromise rotation: if a key is compromised and must be withdrawn, the gateway marks it revoked in its own key table and its hosted verifier rejects receipts signed by it. The JWKS entry does not currently carry a revoked claim, so an offline verifier cannot see the revocation.

Caching guidance

Cache the JWKS for at most 1 hour locally — fetch fresh on every unknown kid to pick up rotations. The endpoint serves Cache-Control: public, max-age=300.

Key naming convention

Keys follow the pattern gw-<region>-<year>-<quarter>:

Example	Meaning
gw-prod-2026-q2	Production gateway, 2026 Q2

Fetch the live JWKS to find the current active key — do not hardcode a kid.