How to Integrate

🔗 How to Integrate

GuardianKey Auth Security can be easily integrated into any authentication system, usually by adding just a few lines of code at the login processing step. For each access attempt, the integration provides a risk score and a recommended action (such as ACCEPT, NOTIFY, BLOCK), enabling dynamic decisions based on configurable security policies.

---

🚀 General Integration Flow

The integration process consists of three main steps:

1. Capture the Login Attempt
   The system collects data such as username, IP, authentication result, and User-Agent.

2. Send the Event to GuardianKey
   This data is sent via a REST call to the GuardianKey API.

3. Act According to the Response
   The system interprets the response (ACCEPT, NOTIFY, BLOCK) and acts accordingly.

---

📥 Backend Flow Example (API v2)

To check the risk of an authentication event using GuardianKey API v2, your backend must:

1. Create a JSON object with the event data (e.g., username, IP, user agent).
2. Encode this object as a JSON string.
3. Calculate a SHA-256 hash of the following concatenation:
   hash("sha256", message_json_string + key + iv)
4. Send a POST request to the GuardianKey endpoint:
   https://api.guardiankey.io/v2/checkaccess

Request Body Structure

The request body must be a JSON object with the following structure:

{
  "authgroupid": "YOUR_AUTHGROUPID",
  "message": "{\"generatedTime\":1754428303,\"agentId\":\"AGENT_ID\",\"organizationId\":\"ORG_ID\",\"authGroupId\":\"AUTHGROUPID\",\"service\":\"SERVICE_NAME\",\"clientIP\":\"189.30.220.10\",\"clientReverse\":\"host.example.com\",\"userName\":\"maria\",\"authMethod\":\"\",\"loginFailed\":0,\"userAgent\":\"Mozilla/5.0...\",\"psychometricTyped\":\"\",\"psychometricImage\":\"\",\"event_type\":\"Authentication\",\"userEmail\":\"[email protected]\"}",
  "hash": "d9c34b6ecbd1a0f2a33b0a0de2a60ff63e8e2d5b8e7153ef32d5de7f57c55f5d"
}

⚠️ Important:
The message field must contain a JSON-encoded string, not a nested object.
The hash is a SHA-256 hash of: message + key + iv

---

✅ Example API Response

{
  "client_os": "Linux",
  "risk_psychometric": "100.0",
  "generatedTime": 1754428303,
  "risk": 5.047,
  "country": "Brazil",
  "eventId": "3e1c389c1ae49efc...",
  "response": "ACCEPT",
  "risk_context": 5.0,
  "risk_intel": 0.05,
  "client_ua": "Chrome",
  "response_cache": 0,
  "message": "Origin not found in the threat DB.",
  "event_token": "06ef74884bfe78d927dbfcb2..."
}

🔐 The response field may contain:

• "ACCEPT" – normal access
• "NOTIFY" – suspicious behavior, consider additional verification (e.g., 2FA)
• "BLOCK" – deny access

The application can then deny access even if the password is correct.

---

💡 Practical Example in PHP

Below is a simplified example of how to integrate the GuardianKey call after the login/password is submitted:

require_once("guardiankey.class.php");
$GK = new guardiankey($GKconfig);

$username = $_POST['user'];
$password = $_POST['password'];

// Authenticate the user with your system as usual
$login_failed = ($username != $password) ? 1 : 0;

$response = $GK->checkaccess($username, $username, $login_failed);
$result = json_decode($response);

if ($result->response === 'BLOCK') {
     echo "Access denied. Please try again later.";
} else {
     echo "Login authorized!";
}

✅ The PHP SDK and others encapsulate event creation and secure sending.

---

📦 Available SDKs

GuardianKey provides SDKs and examples for:

• PHP
• Python
• Node.js
• Java
• .NET
• Ruby
• Lua
• Classic ASP

Request the SDK for your language or check the available integrations.

---

🔐 Security and Encryption

Events can be sent with symmetric encryption (AES-256).

GuardianKey does not collect passwords or interfere with the authentication flow.

---

🔔 Notifications (for NOTIFY or HARD NOTIFY cases)

GuardianKey can notify the user and/or administrator about suspicious access attempts via email.

The message contains a link for the user to confirm if they performed the access.

This user feedback is used to train the model and reduce false positives.

---

✅ Best Practices

• Always validate GuardianKey's response before granting access.
• In case of BLOCK, return a generic message ("invalid username or password") to avoid information leakage.
• Use the real-time risk endpoint and, if desired, also implement offline notifications via webhook.