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 and 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`

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`

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`

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`

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`

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`

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`

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_`
`422`	`application/json` → `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_`
`422`	`application/json` → `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__`
`422`	`application/json` → `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_`
`422`	`application/json` → `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

Responses:

Status	Body
`200`	`application/json` → `ApiResponse_SessionRevokeResponse_`
`422`	`application/json` → `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`

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_`
`422`	`application/json` → `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`	yes
`meta`	`MetaResponse`	no

`ApiResponse_SessionRevokeResponse_`#

Field	Type	Required	Description
`data`	`SessionRevokeResponse`	yes
`meta`	`MetaResponse`	no

`ApiResponse_dict_strAny`#

Field	Type	Required	Description
`data`	object	yes
`meta`	`MetaResponse`	no

`HTTPValidationError`#

Field	Type	Required	Description
`detail`	array of `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
`data`	array of `SessionListItem`	yes
`pagination`	`PaginationMeta`	yes
`meta`	`MetaResponse`	no

`PaginationMeta`#

Pagination metadata.

Field	Type	Required
`page`	`integer`	yes
`per_page`	`integer`	yes
`total_items`	`integer`	yes
`total_pages`	`integer`	yes

`SessionAppInfo`#

Application accessed in a session.

Field	Type	Required
`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`	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
`loc`	array of `string` \| `integer`	yes
`msg`	`string`	yes
`type`	`string`	yes

Sessions API

Authentication#

Endpoints#

GET /api/v1/admin/sessions/#

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

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

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

GET /api/v1/me/sessions#

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

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

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

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

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

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

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

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

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

Schemas#

ApiResponse_SessionResponse_#

ApiResponse_SessionRevokeResponse_#

ApiResponse_dict_str__Any__#

HTTPValidationError#

MetaResponse#

PaginatedResponse_SessionListItem_#

PaginationMeta#

SessionAppInfo#

SessionListItem#

SessionResponse#

SessionRevokeRequest#

SessionRevokeResponse#

ValidationError#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`ApiResponse_SessionResponse_`#

`ApiResponse_SessionRevokeResponse_`#

`ApiResponse_dict_strAny`#

`HTTPValidationError`#

`MetaResponse`#

`PaginatedResponse_SessionListItem_`#

`PaginationMeta`#

`SessionAppInfo`#

`SessionListItem`#

`SessionResponse`#

`SessionRevokeRequest`#

`SessionRevokeResponse`#

`ValidationError`#