---
title: Sessions API
path: reference/api/sessions
status: published
---

# Sessions API

Reference for the `Sessions` endpoint group — 14 endpoints.

Generated from the live OpenAPI spec. Re-run `_generate_api_reference.py` after backend changes.

## Authentication

All endpoints require a Bearer JWT in the `Authorization` header unless noted otherwise. See [Concepts → Tokens and scopes](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/reference/oauth-endpoints) for how to obtain one.

## Endpoints

### **GET** `/api/v1/admin/sessions/`

_List Sessions_

List active sessions with filtering.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `user_id` | query | no | `string` \| `null` |  |
| `tenant_id` | query | no | `string` \| `null` |  |
| `partner_id` | query | no | `string` \| `null` | Filter by partner (all tenants in partner) |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/admin/sessions/revoke-all`

_Revoke All Sessions_

Revoke all sessions for a user or all users in tenant.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → object

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/admin/sessions/{session_id}`

_Revoke Session_

Revoke (delete) a session.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `session_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/admin/sessions/{session_id}`

_Get Session_

Get a session by ID.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `session_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/me/sessions`

_List Sessions_

List all active sessions for the current user.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → object |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/me/sessions/revoke-all`

_Revoke All Sessions_

Revoke all sessions except the current one.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → object |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/me/sessions/{session_id}`

_Revoke Session_

Revoke a specific session.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `session_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → object |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/sessions`

_List Sessions_

List sessions for a tenant.

Can be filtered by user_id to show sessions for a specific user.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `user_id` | query | no | `string` \| `null` | Filter by user ID |
| `active_only` | query | no | `boolean` | Only return active sessions |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`PaginatedResponse_SessionListItem_`](#schema-paginatedresponse-sessionlistitem) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/tenants/{tenant_id}/sessions/revoke-all`

_Revoke All Tenant Sessions_

Revoke all active sessions for a tenant.

This is a destructive operation that will log out all users.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_SessionRevokeResponse_`](#schema-apiresponse-sessionrevokeresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/sessions/stats`

_Get Session Stats_

Get session statistics for a tenant.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_dict_str__Any__`](#schema-apiresponse-dict-str-any) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/sessions/users/{user_id}`

_List User Sessions_

List sessions for a specific user.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `user_id` | path | yes | `string` |  |
| `active_only` | query | no | `boolean` | Only return active sessions |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`PaginatedResponse_SessionListItem_`](#schema-paginatedresponse-sessionlistitem) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/tenants/{tenant_id}/sessions/users/{user_id}/revoke`

_Revoke User Sessions_

Revoke sessions for a user.

Can revoke specific sessions by ID, or all sessions for the user.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `user_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`SessionRevokeRequest`](#schema-sessionrevokerequest)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_SessionRevokeResponse_`](#schema-apiresponse-sessionrevokeresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/tenants/{tenant_id}/sessions/{session_id}`

_Revoke Session_

Revoke a specific session.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `session_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/sessions/{session_id}`

_Get Session_

Get details for a specific session.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `session_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_SessionResponse_`](#schema-apiresponse-sessionresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

## Schemas

Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.

### `ApiResponse_SessionResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`SessionResponse`](#schema-sessionresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ApiResponse_SessionRevokeResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`SessionRevokeResponse`](#schema-sessionrevokeresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ApiResponse_dict_str__Any__`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-validationerror) | no |  |

### `MetaResponse`

Metadata included in API responses.

| Field | Type | Required | Description |
|---|---|---|---|
| `request_id` | `string` \| `null` | no |  |
| `timestamp` | `string` (`date-time`) | no |  |

### `PaginatedResponse_SessionListItem_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of [`SessionListItem`](#schema-sessionlistitem) | yes |  |
| `pagination` | [`PaginationMeta`](#schema-paginationmeta) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `PaginationMeta`

Pagination metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | `integer` | yes |  |
| `per_page` | `integer` | yes |  |
| `total_items` | `integer` | yes |  |
| `total_pages` | `integer` | yes |  |

### `SessionAppInfo`

Application accessed in a session.

| Field | Type | Required | Description |
|---|---|---|---|
| `application_id` | `string` | yes |  |
| `application_name` | `string` | yes |  |
| `accessed_at` | `string` (`date-time`) | yes |  |

### `SessionListItem`

Session list item.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `user_id` | `string` | yes |  |
| `user_email` | `string` \| `null` | no |  |
| `ip_address` | `string` \| `null` | yes |  |
| `user_agent` | `string` \| `null` | yes |  |
| `device_type` | `string` \| `null` | yes |  |
| `is_current` | `boolean` | no | Default: `False` |
| `created_at` | `string` (`date-time`) | yes |  |
| `last_activity_at` | `string` (`date-time`) \| `null` | yes |  |
| `expires_at` | `string` (`date-time`) | yes |  |
| `app_count` | `integer` | no | Default: `0` |

### `SessionResponse`

Session details response.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `user_id` | `string` | yes |  |
| `user_email` | `string` \| `null` | no |  |
| `user_display_name` | `string` \| `null` | no |  |
| `ip_address` | `string` \| `null` | yes |  |
| `user_agent` | `string` \| `null` | yes |  |
| `device_type` | `string` \| `null` | yes |  |
| `location` | `string` \| `null` | yes |  |
| `is_current` | `boolean` | no | Default: `False` |
| `created_at` | `string` (`date-time`) | yes |  |
| `last_activity_at` | `string` (`date-time`) \| `null` | yes |  |
| `expires_at` | `string` (`date-time`) | yes |  |
| `sso_apps` | array of [`SessionAppInfo`](#schema-sessionappinfo) | no | Default: `[]` |

### `SessionRevokeRequest`

Request to revoke sessions.

| Field | Type | Required | Description |
|---|---|---|---|
| `session_ids` | array of `string` \| `null` | no |  |
| `revoke_all` | `boolean` | no | Default: `False` |
| `except_current` | `boolean` | no | Default: `True` |

### `SessionRevokeResponse`

Response for session revocation.

| Field | Type | Required | Description |
|---|---|---|---|
| `revoked_count` | `integer` | yes |  |
| `session_ids` | array of `string` | yes |  |

### `ValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `loc` | array of `string` \| `integer` | yes |  |
| `msg` | `string` | yes |  |
| `type` | `string` | yes |  |