Login History

Track and monitor all login attempts across your organization with comprehensive login history tracking.

Overview

Every login attempt is recorded with detailed metadata including:

IP address
Device type (desktop, mobile, tablet)
Browser and platform information
Login status (success, failed, blocked, 2FA required)
Suspicious activity flags

API Endpoints

User's Login History

Get the authenticated user's own login history.

GET /api/v1/login-history

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `success`, `failed`, `blocked`, `2fa_required`, `2fa_failed`
`from`	date	Start date (YYYY-MM-DD)
`to`	date	End date (YYYY-MM-DD)
`per_page`	integer	Results per page (1-100, default: 25)

Response:

{
  "history": [
    {
      "id": 1,
      "user_id": 3,
      "tenant_id": "acme-corp",
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "device_type": "desktop",
      "browser": "Chrome",
      "platform": "macOS",
      "status": "success",
      "failure_reason": null,
      "is_suspicious": false,
      "created_at": "2025-12-27T20:57:29Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
  }
}

Login Statistics

Get login statistics for the authenticated user.

GET /api/v1/login-history/stats

Response:

{
  "total_logins": 42,
  "logins_last_30_days": 15,
  "failed_attempts_last_30_days": 2,
  "suspicious_logins": 0,
  "unique_ips_last_30_days": 3,
  "devices": {
    "desktop": 12,
    "mobile": 3
  },
  "last_login": "2025-12-27T20:57:29Z"
}

Suspicious Logins

Get logins flagged as suspicious.

GET /api/v1/login-history/suspicious

Query Parameters:

Parameter	Type	Description
`per_page`	integer	Results per page (1-100, default: 25)

Response:

{
  "history": [
    {
      "id": 5,
      "ip_address": "suspicious-ip",
      "device_type": "unknown",
      "is_suspicious": true,
      "created_at": "2025-12-25T10:30:00Z"
    }
  ],
  "pagination": {...}
}

Tenant-wide Login History (Admin)

Get login history for all users in the tenant. Requires admin.audit_log permission.

GET /api/v1/login-history/tenant

Query Parameters:

Parameter	Type	Description
`user_id`	integer	Filter by user ID
`status`	string	Filter by status
`suspicious_only`	boolean	Only show suspicious logins
`from`	date	Start date
`to`	date	End date
`per_page`	integer	Results per page

Response:

{
  "history": [
    {
      "id": 1,
      "user_id": 3,
      "tenant_id": "acme-corp",
      "ip_address": "192.168.1.100",
      "status": "success",
      "is_suspicious": false,
      "created_at": "2025-12-27T20:57:29Z",
      "user": {
        "id": 3,
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  ],
  "pagination": {...}
}

Login Statuses

Status	Description
`success`	Successful login
`failed`	Invalid credentials
`blocked`	Account is inactive or suspended
`2fa_required`	Login pending 2FA verification
`2fa_failed`	Invalid 2FA code provided

Suspicious Login Detection

Logins are flagged as suspicious when:

Login occurs from a new, unrecognized device
Login from a significantly different geographic location
Multiple failed attempts followed by success
Unusual login time patterns

Rate Limiting

To prevent brute force attacks:

5 failed attempts from the same IP triggers a 15-minute lockout
Failed attempts are tracked regardless of the target account
Lockout applies to the IP address, not the user account

Rate Limited Response:

{
  "message": "Too many failed login attempts. Please try again later.",
  "retry_after": 900
}

Best Practices

Regular Monitoring: Review login history periodically for unusual activity
Alert on Suspicious Logins: Set up notifications for suspicious login flags
Geographic Tracking: Note logins from unexpected locations
Device Management: Recognize and track known devices
Failed Attempt Analysis: Investigate patterns of failed login attempts