Manage active sessions

Sessions can be inspected and controlled throughout their lifecycle. Drain for clean upgrades; terminate to end one now; revoke to cut off access immediately and block reattach. See Sessions & revocation.

Requires session permissions

Listing needs session.read; terminate/revoke need session.revoke in the target environment.

List & inspect

List active sessions and inspect one

UIAPICLI

1. Open Operate → Active sessions.
2. Filter by agent, environment, or state, and open a row for its lifecycle detail.

GET/v1/sessions

Copy

curl "$GATEWAY/v1/sessions?environment_id=prod&state=active" \
-H "authorization: Bearer $TOKEN"

View listActiveSessions in the API reference →

Copy

gatewayctl list-sessions --environment prod --format json

Inspect one with gatewayctl inspect-session <client_session_id>.

Drain, terminate, or revoke

Drain, terminate, or revoke a session

UIAPICLI

1. Open the session and choose Drain (finish in‑flight work), Terminate (end now), or Revoke (cut off + block reattach).

POST/v1/sessions/{client_session_id}/revoke

Copy

curl -X POST \
"$GATEWAY/v1/sessions/cs_123/revoke" \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/json" \
--data '{"reason_code": "compromised_agent"}'

View revokeSession in the API reference →

Copy

gatewayctl revoke-session cs_123 --reason compromised_agent

Also: drain-session and terminate-session. Batch via POST /v1/sessions/batch-revoke.

Drain before an upgrade

Draining lets in‑flight calls finish while refusing new ones, so clients reconnect cleanly to an upgraded data plane. Revocation, by contrast, is immediate and intended for governance, not graceful rollout.