> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igrisecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Agent sessions track tool call activity per organization and connection, with a kill switch for immediate control.

# Sessions

Agent sessions are automatically created when an MCP client begins making tool calls through the Igris gateway. They provide a grouping mechanism for related tool calls and a kill switch for immediate control.

Source: `packages/proxy/src/session-manager.ts`, `apps/api/src/routes/sessions.ts`.

## How Sessions Work

When the proxy receives a tool call, Igris checks for an active session for that organization + connection combination. If none exists, one is created automatically.

Each session tracks:

* **Organization** — which org owns this session
* **Connection** — which connection the calls are routed through
* **Status** — `active`, `suspended`, or `completed`
* **Tool call count** — total number of calls in this session
* **Started at** — when the session was created

Sessions expire after **30 minutes of inactivity**. Last-access time is tracked internally for TTL purposes only; there is no `updatedAt` field on the session object.

## Session Deduplication

Igris prevents duplicate sessions for the same org + connection combination. If a session already exists and is active, new tool calls join that session rather than creating a new one. This keeps the audit trail clean and the kill switch effective.

## Kill Switch

The kill switch lets you instantly suspend a session. When suspended:

* All incoming tool calls for that session return a JSON-RPC error: `"Agent session suspended by kill switch"`
* The upstream MCP server receives no further requests
* A `session_suspended` **webhook** is dispatched to any registered webhook endpoints

<Note>
  Suspension dispatches a webhook but does **not** log an audit event and does **not** emit an SSE event. Notification is via webhook only.
</Note>

### Suspending via API

```bash theme={null}
POST https://api.igrisecurity.com/api/v1/sessions/{id}/suspend
Authorization: Bearer <token>
Content-Type: application/json

{ "reason": "Suspected credential exfiltration" }
```

Response:

```json theme={null}
{ "suspended": true }
```

### Resuming via API

```bash theme={null}
POST https://api.igrisecurity.com/api/v1/sessions/{id}/resume
Authorization: Bearer <token>
```

Response:

```json theme={null}
{ "resumed": true }
```

### Listing Sessions

```bash theme={null}
GET https://api.igrisecurity.com/api/v1/sessions?status=active
Authorization: Bearer <token>
```

Filter by `status=active`, `status=suspended`, or `status=completed`. Multiple statuses can be comma-separated.

## Use Cases

* **Incident response** — immediately halt a misbehaving agent without restarting infrastructure
* **Maintenance windows** — suspend sessions during database maintenance
* **Investigation** — pause activity while reviewing anomaly alerts
* **Cost control** — stop a runaway agent racking up API costs

## Related

* [Policies](/govern/policies) — rules that govern what tool calls are allowed in a session
* [Anomaly Detection](/govern/anomaly) — automatic alerts on rate spikes and destructive patterns
* [Tool Calls](/govern/tool-calls) — how `igris.mcp` calls flow through the proxy and are audit-logged