---
title: "Sessions and Revocation"
url: "https://docs.caracal.run/concepts/sessions-revocation/"
markdown_url: "https://docs.caracal.run/markdown/concepts/sessions-revocation.md"
description: "Agent sessions, cascading revocation, and the revocation event stream."
page_type: "page"
concepts: []
requires: []
---

# Sessions and Revocation

Canonical URL: https://docs.caracal.run/concepts/sessions-revocation/
Markdown URL: https://docs.caracal.run/markdown/concepts/sessions-revocation.md
Description: Agent sessions, cascading revocation, and the revocation event stream.
Page type: page
Concepts: none
Requires: none

---

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

```mermaid
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](/concepts/audit-ledger/) to understand how decisions and requests are explained.

## Related Pages

- [Mandates](/concepts/mandate/)
- [Protect an MCP Server](/guides/protect-mcp/)
- [Tail and Query the Audit Stream](/guides/audit-stream/)