Decision tokens

When a checkpoint reaches a terminal decision, Maetra issues a decision token — a signed JWT in decision_token. It binds the decision to the canonical action envelope, exact policy versions, workspace, and intended executor.

Verify it locally for fast rejection, then consume it through POST /v1/executions/authorize immediately before the external action. That authoritative check enforces revocation and one-use semantics.

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": "OKP", "crv": "Ed25519", "alg": "EdDSA", "kid": "…", "x": "…" } ] }

Verifying a token#

Decision tokens are signed with EdDSA using Ed25519. Verify with a JWT library that supports Ed25519 and 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, {
    algorithms: ["EdDSA"],
    issuer: "maetra-govern",
    audience: "payments-worker",
  });
  if (payload.status !== "approved" || payload.maxUses !== 1) {
    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).
• Issuer and audience — require iss=maetra-govern and your executor's exact aud value.
• Binding — recompute and compare actionEnvelopeHash, then compare checkpointId, workspaceId, and policyDigest.
• Use ceiling — require maxUses=1 and authorize through Maetra so a replay or revoked token fails at execution.

Note Treat the token as a short-lived, one-use capability. decision_token_expires_at bounds the token; checkpoint expires_at is the approval timeout.