Get Login History

Get login history for the authenticated user with filtering and pagination.

Quick Navigation

• Endpoint
• Headers
• Query Parameters
• Response
• Success (200)
• Error Codes
• Data Flow
• Features
• Example
• Related Endpoints

Endpoint

GET /api/v1/auth/login-history

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum records to return (default: 50, max: 100)
offset	integer	No	Number of records to skip (default: 0)
filter	string	No	Filter by action: "success", "failure", or null for all

Response

Success (200)

{
  "success": true,
  "data": {
    "history": [
      {
        "id": 456,
        "action": "auth.login.success",
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0...",
        "created_at": "2024-01-01T12:00:00Z",
        "metadata": {
          "method": "password",
          "remember_me": true
        }
      },
      {
        "id": 455,
        "action": "auth.login.failure",
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0...",
        "created_at": "2024-01-01T11:45:00Z",
        "metadata": {
          "reason": "invalid_password"
        }
      }
    ],
    "total_count": 45,
    "limit": 50,
    "offset": 0
  },
  "message": "Login history retrieved successfully"
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing token
500	HISTORY_FETCH_FAILED	Failed to retrieve history

Data Flow

1. Authentication

   • Verify access token
   • Get current user

2. Query Construction

   • Query AuditLog table
   • Filter by user ID
   • Filter by action types (auth.login.success, auth.login.failure)
   • Apply action filter if provided

3. Pagination

   • Apply offset and limit
   • Order by created_at DESC (newest first)

4. Data Formatting

   • Format timestamps as ISO strings
   • Include metadata
   • Include IP address and user agent

5. Response

   • Return paginated results
   • Include total count
   • Include pagination metadata

Features

• Shows successful and failed login attempts
• Includes IP address and user agent for each attempt
• Filter by success/failure
• Paginated results
• Ordered by date (newest first)

Example

curl -X GET "https://api.rivergen.com/api/v1/auth/login-history?limit=20&offset=0&filter=success" \
  -H "Authorization: Bearer <access_token>"

Related Endpoints

• Get Current User - View security summary
• List Sessions - View active sessions