Fraudguard.io is thrilled to unveil the User History Check API, a new tool designed to help you monitor user activities and detect security risks based on a range of customizable factors. Whether it’s unusual locations, new devices, or specific geoblock policies, this API gives you the insights and control you need to protect user accounts effectively. Here’s everything you need to know to integrate and use this new API to its fullest potential.

Key Features of the User History Check API

The User History Check API is organized into three endpoints, offering flexible tracking and analysis of user activities:

  1. POST /api/v1/user-history/check - Logs a new access event, with an optional user_id. If no user_id is provided, a GUID is generated automatically.
  2. GET /api/v1/user-history/{user_id} - Retrieves the most recent activity for a specified user.
  3. GET /api/v1/user-history/list/{user_id} - Returns a full history of user activities, ideal for identifying patterns and trends.

Each event is tracked with key data points, including the IP address, location, timestamp, and user-agent. Combined with customizable recommendations, the API makes it easy to proactively respond to potential threats and bolster your system’s security.

Integration Guide: Setting Up the User History Check API

Step 1: Logging an Access Event

To log a new access event, make a POST request to the /api/v1/user-history/check endpoint. The request requires ip and user_agent, with an optional user_id parameter.

Request Example:

{
  "user_id": "LZsuJGwxV5y7sTF5yFvvFA1LRuH1gVvM",
  "ip": "125.12.194.229",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4280.85 Safari/537.36"
}

If no user_id is provided, the system will generate a new GUID for the user automatically.

Response Example (with auto-generated user_id):

{
  "user_id": "S9zvQIfzSMpi0ZzSXLUDMfh6qhNjfryq",
  "ip": "125.12.194.229",
  "city": "Tokyo",
  "country": "Japan",
  "timestamp": "2024-11-14 03:53:25",
  "user_agent": "Mozilla/5.0 ... Chrome/84.0.4280.85 Safari/537.36",
  "recommendation": {
    "action": "Challenge",
    "reason": "New Device"
  }
}

Step 2: Retrieving the Most Recent Activity

To get the most recent access event for a specific user, send a GET request to /api/v1/user-history/{user_id}.

Request URL: /api/v1/user-history/LZsuJGwxV5y7sTF5yFvvFA1LRuH1gVvM

Response Example:

{
    "user_id": "LZsuJGwxV5y7sTF5yFvvFA1LRuH1gVvM",
    "ip": "125.12.194.229",
    "city": "Tokyo",
    "country": "Japan",
    "timestamp": "2024-11-14 03:53:25",
    "user_agent": "Mozilla/5.0 ... Chrome/84.0.4280.85 Safari/537.36",
    "recommendation": {
        "action": "Challenge",
        "reason": "New Device"
    }
}

This example shows how last_activity includes a recommendation for Challenge, with the reason being a “New Device.”

Step 3: Retrieving the Full Activity History

For auditing purposes or to analyze behavioral trends, you can use the GET /api/v1/user-history/list/{user_id} endpoint, which returns a full history of access events.

Request URL: /api/v1/user-history/list/LZsuJGwxV5y7sTF5yFvvFA1LRuH1gVvM

Response Example:

{
    "user_id": "LZsuJGwxV5y7sTF5yFvvFA1LRuH1gVvM",
    "user_history": [
        {
            "ip": "125.12.194.229",
            "city": "Tokyo",
            "country": "Japan",
            "user_agent": "Mozilla/5.0 ... Chrome/84.0.4280.85 Safari/537.36",
            "timestamp": "2024-11-14 03:53:25",
            "recommendation": {
                "action": "Challenge",
                "reason": "New Device"
            }
        },
        {
            "ip": "1.162.194.229",
            "city": "New Taipei",
            "country": "Taiwan",
            "user_agent": "Mozilla/5.0 ... Chrome/87.0.4280.85 Safari/537.36",
            "timestamp": "2024-11-14 03:49:59",
            "recommendation": {
                "action": "Block",
                "reason": "Bad IP Reputation"
            }
        }
    ]
}

This example shows multiple user access events, each with IP, location, user-agent, timestamp, and recommendation details.

Recommendations: Actions and Reasons

The User History Check API includes recommendation options to help you respond appropriately to each activity:

Recommendation Actions

  • Allow: Grant access with no restrictions.
  • Challenge: Prompt additional verification (e.g., 2FA, SMS verification) due to potential risk.
  • Block: Deny access based on known threats or policies.

Recommendation Reasons

  1. IP in Whitelist: Trusted IP address, allowing access without restriction.
  2. IP in Blacklist: Blocked IP due to known risks.
  3. IP in Geoblock: Access restricted based on geographical policies.
  4. Unusual Location: Attempt from a new or unexpected location.
  5. New Device: Access from an unfamiliar device.
  6. Frequent Login Attempts: Multiple access attempts detected; possible brute-force attack.
  7. Bad IP Reputation: Known low-reputation IP.
  8. Normal Activity: Access consistent with past behavior.
  9. Previous Suspicious Activity: History of suspicious activity from this IP or location.
  10. VPN or Proxy Detected: Use of VPN or proxy detected, requiring further monitoring.

These actions and reasons help you assess risk levels for user access events and determine the best response to secure accounts.

Best Practices for Integrating the User History Check API

  1. Log Each Access Attempt: Always record each login attempt, using both ip and user_agent to track patterns over time.
  2. Follow Recommendation Guidance: Use the action and reason fields to take appropriate measures, whether it’s an Allow, Challenge, or Block.
  3. Automate Responses for High-Risk Actions: Automate Block and Challenge actions to prevent risks in real time based on geolocation, device, and historical IP data.

Conclusion

Fraudguard.io’s User History Check API is a powerful tool for tracking user activities, detecting potential risks, and responding with tailored recommendations. By monitoring each access event, analyzing patterns, and following proactive recommendations, you can significantly enhance account security and reduce fraud.

If you’re ready to integrate this API or need additional support, feel free to reach out. Let’s build safer, more secure systems together!