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

# Sessions and Revocation

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

---

Read this page after [Delegation Constraints](/v1.0/concepts/constraint/). Authority records, Sessions, and Delegations make authority temporary and revocable. A Mandate refers to these records so the Gateway or verified service can reject authority that has ended.

## Identity and Execution Records

| Record                | Role                                                                                                                                                            |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Subject               | Opaque JWT `sub` identity - the application itself by default, or a Federated user. The web console's **Subjects** page groups Authority records by this value.     |
| Authority record      | Immutable record created by an identity or authority exchange; an audit and revocation anchor.                                                                  |
| Root Authority record | First record in an authority ancestry; revoking it can end the descendant authority chain.                                                                      |
| Session               | Governed execution. A delegated Session is still a Session, with an inbound Delegation.                                                                          |

## A Subject Can Be a Federated User

**Subjects** is not a login surface, and a Subject is not only a federated identity. When an application exchanges as itself, the Subject is the application's own identity. When a zone registers an external identity system as a Federated user issuer and the application exchanges an end user's identity token, the Subject is that Federated user: the `sub` is recorded verbatim from the exchanged token, and the resulting Authority record carries no resource authority. Caracal never authenticates Federated users; it federates and records them.

A Session may attach the Federated user's Authority record only while presenting proof of control. That Federated user remains immutable attribution and a revocation anchor for the Session. It does not automatically replace the Application identity on later Resource Mandates and does not create per-Subject scopes.

## Revocation Anchors

Resource servers check every relevant anchor: Authority record ID, Root authority record ID, Session ID, and Delegation ID. The [parsed claim mapping](/v1.0/sdks/identity/#parsed-claim-names) lists the canonical language-level names and raw JWT fields.

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 State as Authority state
  participant Distribution as Revocation distribution
  participant Resource as Gateway or adapter

  Control->>State: Revoke Authority record, Session, or Delegation
  State->>Distribution: Publish revocation anchor
  Resource->>Distribution: Consume revocation
  Resource->>Resource: Cache revoked anchor
  Resource-->>Resource: Reject matching mandates
```

Suspension is reversible Session state, not permanent revocation. Gateway-routed requests perform a fresh STS exchange and reject a suspended Session immediately through authoritative Session validation. Already issued mandates checked directly by a resource verifier can remain usable until their mandate TTL expires; keep mandate TTLs within the documented 15-minute cap when suspension latency matters. Termination and Delegation revocation remain monotonic revocation events.

## Cascade Behavior

Revocation should follow authority:

* revoking an Authority record invalidates authority descended from it;
* revoking a Session invalidates its child Delegations;
* revoking a Delegation invalidates downstream delegated authority;
* revoking a grant prevents future exchange and can invalidate active Authority records and Sessions depending on workflow.

## Resource-Server Responsibility

The Gateway and adapters 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](/v1.0/concepts/audit-ledger/) to understand how decisions and requests are explained.

## Related Pages

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