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

# Sessions

> List, inspect, and revoke active sessions for an application.

Sessions represent active connections between users and your application. Each session tracks connection state, token expiry, and activity timestamps.

## Endpoints

| Method   | Path                                               | Purpose             |
| -------- | -------------------------------------------------- | ------------------- |
| `GET`    | `/applications/:applicationId/sessions`            | List sessions       |
| `GET`    | `/applications/:applicationId/sessions/:sessionId` | Get session         |
| `DELETE` | `/applications/:applicationId/sessions`            | Revoke all sessions |

`applicationId` and `sessionId` path params are UUIDs.

## List sessions

<CodeGroup>
  ```bash curl theme={"system"}
  curl "https://api.kontext.security/api/v1/applications/550e8400-e29b-41d4-a716-446655440000/sessions?limit=50" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { items } = await client.agentSessions.list(
    "550e8400-e29b-41d4-a716-446655440000",
    {
      limit: 50,
    },
  );
  ```
</CodeGroup>

Returns a list of sessions for the application.

### Query parameters

| Parameter         | Type      | Default | Description                                            |
| ----------------- | --------- | ------- | ------------------------------------------------------ |
| `limit`           | `number`  | `100`   | Maximum sessions to return                             |
| `status`          | `string`  | --      | Filter by status: `"active"`, `"inactive"`, or `"all"` |
| `includeInactive` | `boolean` | `false` | Include disconnected/expired sessions                  |

## Get session

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.kontext.security/api/v1/applications/550e8400-e29b-41d4-a716-446655440000/sessions/44444444-4444-4444-8444-444444444444 \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { session } = await client.agentSessions.get(
    "550e8400-e29b-41d4-a716-446655440000",
    "44444444-4444-4444-8444-444444444444",
  );
  ```
</CodeGroup>

### Session object

Response shape: `{ "session": { ... } }`

| Field            | Type             | Description                                         |
| ---------------- | ---------------- | --------------------------------------------------- |
| `id`             | `string`         | Session UUID                                        |
| `name`           | `string`         | Human-readable session name                         |
| `status`         | `string`         | Session status: `"active"` or `"disconnected"`      |
| `derivedStatus`  | `string`         | Computed status (see below)                         |
| `tokenExpiresAt` | `string?`        | ISO 8601 timestamp when the session token expires   |
| `lastActiveAt`   | `string?`        | ISO 8601 timestamp of last activity                 |
| `connectedAt`    | `string?`        | ISO 8601 timestamp when the session was established |
| `disconnectedAt` | `string?`        | ISO 8601 timestamp when disconnected                |
| `createdAt`      | `string`         | ISO 8601 timestamp                                  |
| `agentId`        | `string`         | Application ID that created this session            |
| `organizationId` | `string`         | Owning organization ID                              |
| `hostname`       | `string \| null` | Hostname reported by the MCP client                 |
| `userAgent`      | `string \| null` | User agent reported by the MCP client               |
| `clientInfo`     | `object \| null` | MCP client metadata                                 |

### Derived status values

| Status         | Meaning                                |
| -------------- | -------------------------------------- |
| `active`       | Connected and has been active recently |
| `idle`         | Connected but no recent activity       |
| `expired`      | Token has expired                      |
| `disconnected` | Transport connection is closed         |

## Revoke all sessions

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X DELETE https://api.kontext.security/api/v1/applications/550e8400-e29b-41d4-a716-446655440000/sessions \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { success, disconnectedCount } = await client.agentSessions.revokeAll(
    "550e8400-e29b-41d4-a716-446655440000",
  );
  ```
</CodeGroup>

Terminates all active sessions for the application. Connected clients receive a disconnect event and need to re-authenticate.

### Response

| Field               | Type      | Description                             |
| ------------------- | --------- | --------------------------------------- |
| `success`           | `boolean` | Always `true` on success                |
| `disconnectedCount` | `number`  | Number of sessions that were terminated |