Decision tokens

When a checkpoint reaches a terminal decision, Maetra issues a decision token — a signed JWT in decision_token. It's cryptographic proof that a specific action was authorised, and it verifies offline, without calling back to Maetra.

Use it to gate the action at the point of execution: a downstream service can accept the token, verify it, and be certain the action passed governance.

Public keys (JWKS)#

GET /.well-known/jwks.json — no authentication required. Returns the key set used to sign decision tokens. Fetch once and cache; the token header's kid identifies which key signed it.

curl "https://api.maetra.io/.well-known/jwks.json" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

{ "keys": [ { "kty": "EC", "crv": "P-256", "kid": "2026-06", "x": "…", "y": "…" } ] }

Verifying a token#

Decision tokens are signed with ES256 (ECDSA P-256). Verify with any standard JWT library using the JWKS above.

import { jwtVerify, createRemoteJWKSet } from "jose";


const JWKS = createRemoteJWKSet(new URL("https://api.maetra.io/.well-known/jwks.json"));


export async function verifyDecision(token: string) {
  const { payload } = await jwtVerify(token, JWKS);
  if (payload.status !== "approved") {
    throw new Error(`Action not approved: ${payload.status}`);
  }
  return payload; // identifies the checkpoint, action, decision, and expiry
}

What to check

• Signature — must validate against a key in the JWKS.
• status — proceed only when approved.
• Expiry — reject expired tokens (standard exp).
• Binding — confirm the token's checkpoint/action matches the action you're about to perform, so a token for one action can't authorise another.

Note Treat the token as a short-lived capability: verify it immediately before acting, not minutes later. The checkpoint's expires_at bounds its validity.