v4

latestOpenAPI 3.1.1Apache 2.02026-07-31107278570.4 KB

Sessions

List user sessions

Retrieves a paginated list of all sessions associated with a specific user across all devices and browsers. Use this endpoint to audit user activity, display all active sessions in account management interfaces, or verify user authentication status across devices. Supports filtering by session status (active, expired, revoked, logout) and time range (creation date). Returns session details for each session including device information, IP address, geolocation, and current status. The response includes pagination metadata (page tokens and total count) to handle large session lists efficiently.

get/api/v1/users/{user_id}/sessions

Path parameters

user_idstring required

Unique identifier for the user whose sessions to retrieve. Must start with 'usr_' prefix.

Query parameters

page_sizeinteger

Maximum number of sessions to return in a single page. Optional parameter. If not specified, defaults to a server-defined limit. Use smaller values for faster responses, larger values for fewer requests.

page_tokenstring

Pagination token from the previous response for retrieving the next page of results. Leave empty for the first page. Use the next_page_token from a previous response to fetch subsequent pages.

filter.statusstring[]

Filter sessions by one or more status values. Possible values: 'active', 'expired', 'revoked', 'logout'. Leave empty to include all statuses. Multiple values use OR logic (e.g., status=['active', 'expired'] returns sessions that are either active OR expired).

filter.start_timestring date-time

Filter to include only sessions created on or after this timestamp. Optional. Uses RFC 3339 format. Useful for querying sessions within a specific time window.

filter.end_timestring date-time

Filter to include only sessions created on or before this timestamp. Optional. Uses RFC 3339 format. Must be after start_time if both are specified.

Response

Successfully retrieved user sessions. Returns a list of sessions with pagination information

next_page_tokenstring

Pagination token for retrieving the next page of results. Empty string if there are no more pages (you have reached the final page of results).

prev_page_tokenstring

Pagination token for retrieving the previous page of results. Empty string for the first page. Use this to navigate backward through result pages.

total_sizeinteger

Total number of sessions matching the applied filter criteria, regardless of pagination. This represents the complete result set size before pagination is applied.

Example response

{
  "next_page_token": "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAic2VzXzEyMzQ1In0=",
  "prev_page_token": "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInNlc183OTAxIn0=",
  "sessions": [
    {
      "absolute_expires_at": "2025-01-22T10:30:00Z",
      "authenticated_clients": [
        {
          "client_id": "skc_1234567890",
          "organization_id": "org_1234567890"
        }
      ],
      "authenticated_organizations": [
        "org_123",
        "org_456"
      ],
      "created_at": "2025-01-15T10:30:00Z",
      "device": {
        "browser": "Chrome",
        "browser_version": "120.0.0.0",
        "device_type": "desktop",
        "ip": "192.0.2.1",
        "location": {
          "city": "San Francisco",
          "latitude": "37.7749",
          "longitude": "-122.4194",
          "region": "United States",
          "region_subdivision": "CA"
        },
        "os": "macOS",
        "os_version": "14.2",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "expired_at": "2025-01-15T12:00:00Z",
      "idle_expires_at": "2025-01-15T11:30:00Z",
      "last_active_at": "2025-01-15T10:55:30Z",
      "logout_at": "2025-01-15T14:00:00Z",
      "organization_id": "org_1234567890123456",
      "session_id": "ses_1234567890123456",
      "status": "active",
      "updated_at": "2025-01-15T10:45:00Z",
      "user_id": "usr_1234567890123456"
    }
  ],
  "total_size": 42
}