Sessions and Revocation

Operate

Sessions and Revocation

V1 sessions are explicit runtime state for governed MCP calls. They are not a broad session platform. The gateway stores durable metadata in PostgreSQL, keeps hot lookup state in Valkey, tracks affinity, and emits metadata-only audit for lifecycle changes.

Audience

• Operators draining or terminating active sessions.
• Security admins revoking users, agents, credential bindings, connectors, tools, or sessions.
• Release owners proving upgrade/drain behavior.
• Security reviewers checking that revocation affects active work.

What is this?

This page covers client sessions, backend sessions, affinity, reconnect/reattach, drain, terminate, revoke, expiry, failure, and revocation fanout. Reconnect is supported only when the session and backend are eligible for resume. Transparent live stream migration is not a V1 promise.

When do I use it?

Use it before an upgrade, connector or credential incident, emergency disable, or security review that asks whether active sessions are still allowed after revocation.

What happens?

1. A client session is created with tenant, environment, client surface, actor or agent context, durable metadata, affinity, backend sessions, and allowed transitions.
2. Reattach can reuse an existing client session ID when the record is valid.
3. Reconnect can use metadata reattach or backend resume only when backend support exists.
4. Drain moves runtime workers into no-new-stateful-session behavior and records gateway_draining style denials before upstream execution.
5. Terminate closes active sessions and removes hot index state.
6. Revoke uses PostgreSQL outbox/internal queue fanout, blocks new calls, and revokes or terminates affected client and backend sessions.
7. Lifecycle audit records request IDs, correlation IDs, policy version, credential mode, outcome, reason code, redaction status, and no payload or secret logging.

State table

State	Operator meaning
pending	Session setup has not completed; do not assume backend affinity exists.
active	Session can serve governed calls if policy, credential, connector, and route checks still pass.
reconnecting	Resume is in progress; backend support is required for backend resume.
draining	New stateful sessions are refused while existing work completes or times out.
terminated	Operator or drain flow has closed the session.
revoked	Revocation fanout has blocked the session path.
expired	Idle or max-duration limits closed the session.
failed	Lifecycle failed with a machine reason; investigate before retrying.

Revocation targets

Revocation can target users, agents, agent instances, client sessions, credential bindings, connectors, policies, client surfaces, MCP servers, tools, API sources, and selected operations when the contract names them. The effects must include blocksNewCalls=true; active-session termination depends on affected scope.

What can go wrong?

• A page promises transparent live migration for a backend that cannot resume or replay state.
• Runtime only keeps worker memory and loses durable session truth. The contract requires PostgreSQL metadata and Valkey hot indexes.
• Drain accepts new stateful sessions or reaches upstream before denial.
• Revocation blocks future calls but leaves affected active sessions usable where the contract says they must be terminated or revoked.
• Duplicate outbox delivery is not idempotent.
• Audit or evidence captures prompts, tool payloads, request bodies, response bodies, tokens, credentials, or secret material.

Source truth

• contracts/jsonschema/session-lifecycle.schema.json
• contracts/jsonschema/revocation-event.schema.json
• docs/product/prd-acceptance-map.md

Next

• Read Connectors and Private Routing when the affected scope includes a connector.
• Read Release Evidence for upgrade/drain proof.
• Read Security Review for revocation control review.