Skip to main content

Quick Start

Send your first event and get a live risk score in under 5 minutes.

Step 1 — Create an App & API Key​

In the Humifortis dashboard → Apps & Keys → New App.

Give it a name (e.g. "My App"), copy the generated API key. Each app gets its own key with independent risk band configuration.

Step 2 — Send an Authentication Event​

curl -X POST https://your-humifortis-instance/api/v1/events \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "event_id": "550e8400-e29b-41d4-a716-446655440000",
      "entity_id": "user:alice@example.com",
      "entity_type": "user",
      "event_type": "auth.login.failed",
      "timestamp": "2025-12-16T10:00:00Z",
      "source": "my-app",
      "metadata": {
        "ip_address": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "country": "FR"
      }
    }
  }'

Response — 202 Accepted:

{
  "accepted": 1,
  "rejected": 0,
  "errors": []
}

Events are processed asynchronously. The 202 means the event was queued. Risk state is updated in Redis within milliseconds.

Step 3 — Query the Risk Score​

curl https://your-humifortis-instance/api/v1/risk/user:alice@example.com \
  -H "X-API-Key: YOUR_API_KEY"
{
  "entity_id": "user:alice@example.com",
  "entity_type": "user",
  "risk_score": 12.5,
  "risk_level": "LOW",
  "event_count": 1,
  "contributing_factors": ["AUTH_LOGIN_FAILED"],
  "last_updated": "2025-12-16T10:00:01Z"
}

Step 4 — Trigger an Enforcement​

Send a few more failed logins to push the score into HIGH territory, then query again:

# Send 5 more failed logins
for i in {1..5}; do
  curl -s -X POST https://your-humifortis-instance/api/v1/events \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"event":{"event_id":"'$(uuidgen)'","entity_id":"user:alice@example.com","entity_type":"user","event_type":"auth.login.failed","timestamp":"2025-12-16T10:00:00Z","metadata":{"ip_address":"203.0.113.42"}}}'
done

# Check the score — should now be HIGH or CRITICAL
curl https://your-humifortis-instance/api/v1/risk/user:alice@example.com \
  -H "X-API-Key: YOUR_API_KEY"

If a playbook rule is configured for HIGH risk, GET /risk will reflect the elevated score. Use POST /evaluate to get the inline enforcement decision (CHALLENGE_MFA or BLOCK).

Using with the Keycloak Connector​

If you use Keycloak, the connector handles steps 2–4 automatically on every login. You don't need to send events manually.

→ Keycloak Connector

Event Format Reference​

FieldRequiredDescription
event.event_idYesUnique event ID from your system (UUID recommended)
event.entity_idYesIdentity being scored: user:alice@example.com, device:fp_abc123
event.entity_typeYesuser, session, token, api_key, device
event.event_typeYesDot-namespaced event name (e.g. auth.login.failed)
event.timestampYesISO 8601 UTC
event.metadata.ip_addressNoSource IP — used for geo, Tor, and VPN detection
event.metadata.user_agentNoBrowser/client user-agent — used for device fingerprinting
event.metadataNoArbitrary key-value pairs forwarded to the signal engine

Next Steps​