Get Session History

GET/web/v1/system/security/sessions/history JWT

Required Gateway Headers

All API requests require gateway headers. See Required Headers for the complete list. In local/test environments, you must also include Cloudflare simulation headers (CF-Connecting-IP, Cf-Ray, cf-ipcountry).

Retrieves paginated login history for the authenticated user. Supports time-range filtering. Results are ordered by login time descending (most recent first).

Required Headers

Header	Example Value	Description
Content-Type	application/json	Request content type
Accept	application/json	Expected response type
X-Client-Hash		Client device fingerprint
Accept-Language	en, zh, zh-Hant, ja, vi	Response language (default: en)
Authorization	Bearer	JWT access token

Request Parameters

Name	Type	Required	In	Description
page	Integer	Required	query	Page number, zero-based (default: 0)
size	Integer	Required	query	Page size (default: 20, max: 100)
startTime	Instant	Required	query	Filter start time (ISO 8601 datetime)
endTime	Instant	Required	query	Filter end time (ISO 8601 datetime)

Request Example

No request body required. Parameters are passed as query strings.

Success Response

Success 200

{
  "version": "2.0.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "content": [
      {
        "eventType": "LOGIN_SUCCESS",
        "ipAddress": "127.0.0.1",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "deviceInfo": "Windows 10 - Chrome 120",
        "location": {
          "city": "San Francisco",
          "region": "CA",
          "country": "US",
          "lat": 37.7749,
          "lon": -122.4194
        },
        "status": "SUCCESS",
        "failureReason": null,
        "mfaMethod": "OTP",
        "sessionId": "SESS...C_001",
        "createdAt": "2026-03-23T12:00:00Z"
      },
      {
        "eventType": "LOGIN_FAILED",
        "ipAddress": "127.0.0.2",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15",
        "deviceInfo": "macOS 10.15 - Safari 17",
        "location": null,
        "status": "FAILED",
        "failureReason": "INVALID_CREDENTIALS",
        "mfaMethod": null,
        "sessionId": null,
        "createdAt": "2026-03-23T11:30:00Z"
      }
    ],
    "totalElements": 2,
    "totalPages": 1,
    "number": 0,
    "size": 20
  }
}

Field	Type	Description
eventType	string	Type of login event (e.g. "LOGIN_SUCCESS", "LOGIN_FAILED", "LOGOUT", "SESSION_EXPIRED")
ipAddress	string	Client IP address
userAgent	string	Raw User-Agent string
deviceInfo	string	Human-readable device/browser summary (e.g. "Windows 10 - Chrome 120")
location	object or null	Geo-location object derived from IP, null if unavailable
location.city	string	City name
location.region	string	Region/state code
location.country	string	ISO country code
location.lat	number	Latitude
location.lon	number	Longitude
status	string	Outcome status: "SUCCESS" or "FAILED"
failureReason	string or null	Failure reason (e.g. "INVALID_CREDENTIALS", "MFA_FAILED") if login failed, otherwise null
mfaMethod	string or null	MFA method used (e.g. "OTP", "EMAIL", "BACKUP_CODE"), null if MFA was not involved
sessionId	string or null	Associated session ID (masked), null for failed attempts
createdAt	string (ISO 8601)	Timestamp of the event

Pagination wrapper fields: totalElements, totalPages, number (current page), size (page size).

Error Responses

Unauthorized 401

{
  "success": false,
  "code": "4010",
  "message": "Invalid or expired token"
}

Notes

• Results are ordered by createdAt descending (most recent first).
• Both startTime and endTime must be provided together for time-range filtering; if either is missing, all history is returned.
• Maximum page size is 100.
• location is derived from IP geolocation and may be null if the IP cannot be resolved.
• deviceInfo is a server-parsed summary of the userAgent string for display purposes.
• sessionId is masked (first 4 chars + ... + last 4 chars) for security.