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 connector that fits your framework; use lower-level packages only when you are building a custom boundary.
Which Layer Should I Use?
Section titled “Which Layer Should I Use?”| Need | Use |
|---|---|
| Express route middleware | Express Connector |
| FastAPI/Starlette (ASGI) middleware | ASGI Connector |
| FastMCP server or tool authentication | FastMCP Connector |
Go net/http middleware | Go net/http Connector |
| Framework-neutral bearer parsing and mandate verification | MCP Auth Transport |
| Custom JWT claim verification | Identity Package |
| Shared revocation checks | Revocation Package plus Redis Revocation Store |
| Durable TypeScript token state | Postgres Token State Backend |
Framework Connectors
Section titled “Framework Connectors”Connectors adapt the shared transport 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 connectors first when your framework is supported. They reduce boilerplate and keep error mapping consistent with the rest of Caracal.
MCP Auth Transport
Section titled “MCP Auth Transport”MCP Auth Transport is the reusable verification layer under the connectors. Use it when your framework is unsupported or when you need direct control over bearer parsing, verifier defaults, route-level scopes, targets, agent 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 connector. It does not provide the full transport 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 revoked sessions, root sessions, agent sessions, or delegation edges. Use in-memory revocation stores for local development only. Use Redis Revocation Store for multi-instance resource servers that consume caracal.sessions.revoke.
Use Postgres Token State Backend only when a TypeScript service needs durable token-state rows. It is not the revocation stream consumer.
Failure Behavior
Section titled “Failure Behavior”All HTTP verification layers should preserve the shared status mapping:
| Status | Meaning |
|---|---|
401 | The credential was missing, invalid, expired, revoked, or from the wrong zone. |
403 | The mandate verified but lacks required scope, target, agent, delegation, chain, or hop authority. |