Sessions and Revocation

Sessions make Caracal authority temporary and revocable. A mandate includes session anchors, and resource servers check those anchors before accepting the mandate.

Session Types

Session	Role
Subject session	Original authenticated user or service context. Also called the authority session in the web console.
Agent session	Runtime context for a spawned agent.
Delegated session	An agent session that holds an inbound delegation edge — a state of an agent session, not a separate object.

Revocation Anchors

Resource servers check every relevant anchor:

session ID;
root session ID;
agent session ID;
delegation edge ID.

If any anchor is revoked, the mandate should be rejected as session_revoked.

Revocation Flow

sequenceDiagram
  participant Control as Console or Admin API
  participant Store as Postgres
  participant Stream as Redis revocation stream
  participant Resource as Gateway or connector

  Control->>Store: Revoke grant, session, agent, or edge
  Store->>Stream: Publish revocation anchor
  Resource->>Stream: Consume caracal.sessions.revoke
  Resource->>Resource: Cache revoked anchor
  Resource-->>Resource: Reject matching mandates

The Redis stream name is caracal.sessions.revoke. Redis-backed connector packages can consume the stream and populate local revocation stores.

Cascade Behavior

Revocation should follow authority:

revoking a subject session invalidates derived agent sessions;
revoking an agent session invalidates its child edges;
revoking a delegation edge invalidates downstream delegated authority;
revoking a grant prevents future exchange and can invalidate active sessions depending on workflow.

Resource-Server Responsibility

The Gateway and connectors must be configured with a revocation store. For development, an in-memory store can be useful. For production, use a shared store and stream consumer so revocations propagate across resource-server instances.

Next Step

Read Audit and Request Traces to understand how decisions and requests are explained.