Skip to main content

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.

🛡️ Pseudonymous User Identifiers​

GuardianKey does not require a clear-text username to calculate risk. The client integration may pseudonymize the user identifier before sending the event, for example by applying a consistent cryptographic hash. The same stable pseudonymous value must be used in subsequent events so the behavioral engine can correlate activity and maintain the user's baseline without receiving the original username.

Passwords and authentication secrets must never be placed in the user identifier or sent as event attributes.

📥 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​

GuardianKey API endpoints support HTTPS with TLS 1.3, protecting event communication between the source integration and the service. Integrations should validate the server certificate and use a secure TLS profile throughout the communication path.

Events can use symmetric encryption with AES-256. Supported identity and authentication flows also use asymmetric RSA and ECDSA cryptography for digital signatures, request validation, and WebAuthn operations. These controls provide confidentiality, integrity, and authenticity for supported end-to-end integration flows.

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.