Login History

View login history and authentication events through the audit log system.

Overview

EntryGuard does not have a dedicated "login history" endpoint. Instead, all authentication events, including logins, are captured in the comprehensive audit log system.

Login events are recorded in the audit log with the event type USER_LOGIN. To view login history, use the audit logs endpoint with appropriate filters.

curl -X GET "https://api.entryguard.io/api/v1/audit-logs?eventType=USER_LOGIN&page=0&size=20" \
  -H "Authorization: Bearer {adminAccessToken}"

curl -X GET "https://api.entryguard.io/api/v1/audit-logs?eventType=USER_LOGIN&userId={userId}&page=0&size=20" \
  -H "Authorization: Bearer {adminAccessToken}"

curl -X GET "https://api.entryguard.io/api/v1/audit-logs?eventType=USER_LOGIN&page=0&size=10&sort=timestamp,desc" \
  -H "Authorization: Bearer {adminAccessToken}"

Field	Description
id	Unique event ID (UUID)
eventType	Always "USER_LOGIN" for login events
userId	ID of the user who logged in
userEmail	Email address of the user
userName	Name of the user
timestamp	When the login occurred (ISO 8601 timestamp)
ipAddress	IP address from which the login originated
metadata	Additional context (device, browser, location if available)
success	Whether the login was successful

{
  "content": [
    {
      "id": "7f8a9b0c-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
      "eventType": "USER_LOGIN",
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "userEmail": "[email protected]",
      "userName": "John Doe",
      "organizationId": "223e4567-e89b-12d3-a456-426614174001",
      "timestamp": "2024-02-18T10:30:00Z",
      "ipAddress": "203.0.113.42",
      "metadata": {
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
        "success": true,
        "mfaUsed": true,
        "location": "San Francisco, CA, US"
      }
    },
    {
      "id": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0f1a2b3c",
      "eventType": "USER_LOGIN",
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "userEmail": "[email protected]",
      "userName": "John Doe",
      "organizationId": "223e4567-e89b-12d3-a456-426614174001",
      "timestamp": "2024-02-17T15:45:00Z",
      "ipAddress": "203.0.113.42",
      "metadata": {
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)...",
        "success": true,
        "mfaUsed": true,
        "location": "San Francisco, CA, US"
      }
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalPages": 5,
  "totalElements": 87,
  "last": false,
  "first": true,
  "size": 20,
  "number": 0,
  "numberOfElements": 20,
  "empty": false
}

Other Authentication Events

The audit log also captures other authentication-related events:

Event Type	Description
USER_LOGIN	Successful user login
USER_LOGIN_FAILED	Failed login attempt
USER_LOGOUT	User logout
USER_PASSWORD_CHANGED	Password change
USER_PASSWORD_RESET	Password reset via email
USER_MFA_ENABLED	MFA enabled for user
USER_MFA_DISABLED	MFA disabled for user
USER_CREATED	New user created (invitation sent)
USER_DELETED	User deleted

Get All Authentication Events

curl -X GET "https://api.entryguard.io/api/v1/audit-logs?eventType=USER_LOGIN,USER_LOGIN_FAILED,USER_LOGOUT,USER_PASSWORD_CHANGED&page=0&size=20" \
  -H "Authorization: Bearer {adminAccessToken}"

Authentication

The audit logs endpoint requires admin authentication:

Authorization: Bearer {adminAccessToken}

Only organization admins (isOrgAdmin: true) can access audit logs. Regular users cannot view login history.

Query Parameters

When querying the audit logs endpoint for login history:

Parameter	Type	Description
eventType	string	Filter by event type (use "USER_LOGIN" for login events)
userId	string (UUID)	Filter by specific user ID
startDate	string (ISO 8601)	Filter events after this date
endDate	string (ISO 8601)	Filter events before this date
page	number	Page number (0-indexed)
size	number	Number of events per page (default: 20, max: 100)
sort	string	Sort order (e.g., "timestamp,desc")

Use Cases

Security Monitoring

Monitor login patterns to detect:

Unusual login times
Logins from unexpected locations
Multiple failed login attempts
Concurrent logins from different IPs

Compliance

Generate login history reports for:

SOC 2 compliance
GDPR data access requests
Internal security audits
Incident investigations

User Support

Help users troubleshoot:

"I didn't receive my login notification"
"Was my account accessed from another location?"
"When was my last successful login?"

# Get failed login attempts for the last 24 hours
curl -X GET "https://api.entryguard.io/api/v1/audit-logs?eventType=USER_LOGIN_FAILED&startDate=2024-02-17T00:00:00Z&endDate=2024-02-18T00:00:00Z&page=0&size=50" \
  -H "Authorization: Bearer {adminAccessToken}"

{
  "id": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
  "eventType": "USER_LOGIN_FAILED",
  "userId": null,
  "userEmail": "[email protected]",
  "userName": null,
  "organizationId": "223e4567-e89b-12d3-a456-426614174001",
  "timestamp": "2024-02-18T08:15:00Z",
  "ipAddress": "198.51.100.42",
  "metadata": {
    "reason": "Invalid password",
    "attempts": 3,
    "userAgent": "Mozilla/5.0..."
  }
}

Audit Logs - Complete audit logs documentation
Login - User authentication endpoint

Best Practices

Regular Monitoring: Review login events regularly for security anomalies
Alert Setup: Configure alerts for suspicious login patterns
Retention Policy: Ensure audit logs are retained per your compliance requirements
Access Control: Limit audit log access to authorized admins only
Export Reports: Export login history for compliance audits and security reviews

Frontend Implementation Example

// JavaScript example - fetch recent logins for current user
async function getMyLoginHistory() {
  const user = JSON.parse(localStorage.getItem('user'));
  const accessToken = localStorage.getItem('accessToken');

  try {
    const response = await fetch(
      `https://api.entryguard.io/api/v1/audit-logs?eventType=USER_LOGIN&userId=${user.id}&page=0&size=10&sort=timestamp,desc`,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`
        }
      }
    );

    if (response.ok) {
      const data = await response.json();
      return data.content.map(event => ({
        timestamp: new Date(event.timestamp),
        ipAddress: event.ipAddress,
        location: event.metadata?.location,
        device: event.metadata?.userAgent,
        success: event.metadata?.success
      }));
    } else {
      console.error('Failed to fetch login history');
      return [];
    }
  } catch (error) {
    console.error('Error fetching login history:', error);
    return [];
  }
}

Overview​

Viewing Login History​

Get All Login Events​

Get Login Events for a Specific User​

Get Recent Login Events​

Login Event Details​

Example Login Event Response​

Other Authentication Events​

Get All Authentication Events​

Authentication​

Query Parameters​

Use Cases​

Security Monitoring​

Compliance​

User Support​

Example: Failed Login Analysis​

Failed Login Event Example​

Related Endpoints​

Best Practices​

Frontend Implementation Example​

Overview

Viewing Login History

Get All Login Events

Get Login Events for a Specific User

Get Recent Login Events

Login Event Details

Example Login Event Response