MudraID — a trust layer for AI agents

Every error is one JSON shape. Build alerting on it.

{
  "error_code": "MISSING_SCOPE",
  "message": "required scope 'items:write' not present in token"
}

V1 codes

Status	error_code	Cause
401	`MISSING_TOKEN`	`Authorization` header missing or not `Bearer`
401	`INVALID_TOKEN`	Malformed JWT or invalid signature
401	`EXPIRED_TOKEN`	`exp` is in the past
401	`TOKEN_NOT_YET_VALID`	`nbf` is in the future
401	`WRONG_AUDIENCE`	`aud` doesn’t match the accepted audience (`expected_audience`, or the YAML `platform_id` when unset)
401	`WRONG_ISSUER`	`iss` isn’t an accepted MudraID issuer (default `mudraid-identity`; configurable)
403	`MISSING_SCOPE`	Token valid but required scope absent
404	`ROUTE_NOT_FOUND`	No YAML rule, or `skip: true`. Indistinguishable on purpose
500	`JWKS_UNAVAILABLE`	Couldn’t fetch JWKS to verify. Operator-side, not credential-side
500	`MIDDLEWARE_NOT_READY`	YAML couldn’t be loaded or parsed

V2 mode

V2 uses the same {"error_code", "message"} shape. Every refusal is closed — nothing that cannot be decided reaches your handler.

Status	error_code	Cause
400	`ENFORCE_BODY_UNREADABLE`	The request body couldn’t be read
400	`ENFORCE_MALFORMED_REQUEST`	Not a single JSON-RPC 2.0 object, or a malformed `tools/call`
400	`ENFORCE_BATCH_UNSUPPORTED`	A JSON-RPC batch (array); never partially evaluated
403	`ENFORCE_MESSAGE_NOT_ALLOWED`	A JSON-RPC method that is neither `tools/call` nor in `public_methods`
403	`ENFORCE_ACTION_UNMAPPED`	No exact canonical action is mapped for this tool in the signed bundle
403	`ENFORCE_DECISION_DENY`	`/decide` refused the action
405	`ENFORCE_METHOD_NOT_ALLOWED`	An HTTP method the MCP transport doesn’t accept on a protected path
413	`ENFORCE_BODY_TOO_LARGE`	Body over `max_body_bytes`
503	`ENFORCE_NO_VALID_BUNDLE`	No verified signed bundle is active yet
503	`ENFORCE_DECIDE_UNAVAILABLE`	`/decide` timed out, errored or was unreachable, or the client is not configured to call it
503	`ENFORCE_TRUSTED_CONTEXT_UNREPRESENTABLE`	An allow could not be passed to your handler as headers; the request was not forwarded

Behind this contract: a full unit suite covering every failure shape, the JWKS rotation recovery path, thread safety, and the anti-leak guarantee that no token or secret appears in middleware logs. For how to act on each code, see Interpret verification error codes.