Verification Layer Overview
Use this page when you are protecting an inbound resource-server boundary and need to choose the right package layer. Start with the highest-level adapter that fits your framework; use lower-level packages only when you are building a custom boundary.
The verification layer consumes use=resource mandates at a resource server. Gateway ingress consumes use=gateway mandates instead. A Session or lifecycle mandate must not be accepted at either boundary. The classes are defined in Mandate Use Classes.
Which Layer Should I Use?
Section titled “Which Layer Should I Use?”| Need | Use |
|---|---|
| Express route middleware | Express Adapter |
| FastAPI/Starlette (ASGI) middleware | ASGI Adapter |
| FastMCP server or tool authentication | FastMCP Adapter |
Go net/http middleware | Go net/http Adapter |
| Framework-neutral bearer parsing and mandate verification | Verify Package |
| Custom JWT claim verification | Identity Package |
| Shared revocation checks | Revocation Package plus Redis Revocation Store |
Framework Adapters
Section titled “Framework Adapters”Adapters bind the shared verify and identity packages to common server frameworks. They should reject failed requests before your handler or tool runs, attach verified claims to framework context, and preserve the same 401/403 behavior across languages.
Use adapters first when your framework is supported. They reduce boilerplate and keep error mapping consistent with the rest of Caracal.
Verify Package
Section titled “Verify Package”Verify Package is the reusable verification engine under the adapters. Use it when your framework is unsupported or when you need direct control over bearer parsing, verifier defaults, route-level scopes, targets, Session requirements, Delegation requirements, hop limits, and safe error hints.
Identity Package
Section titled “Identity Package”Identity Package verifies mandate JWT claims directly. Use it when you are composing a custom verifier or adapter. It does not provide the full verify-engine error mapping or revocation-store integration by itself.
Revocation and Shared State
Section titled “Revocation and Shared State”Resource servers must reject mandates anchored to a revoked Authority record ID, Root authority record ID, Session ID, or Delegation ID. Use in-memory revocation stores for local development only. Use Redis Revocation Store for multi-instance resource servers that consume the protocol stream caracal.sessions.revoke.
Failure Behavior
Section titled “Failure Behavior”All HTTP verification layers preserve one status contract - 401 when the credential itself was not accepted, 403 when a verified mandate lacks the route’s required authority. The canonical per-code mapping and the shared status function live in Framework Adapters; the code catalog is in Error Codes.
JWT verification establishes signed claims; revocation checks establish whether their authority remains active. Both are required where revocation-before-expiry is part of the resource’s security contract.