Sessions API

A session is a group of related events that belong to the same user visit — for example a login followed by a payment. Naiza does not create sessions for you; you associate events with a session by sending the same sessionId on each event. Sessions power the grouped timeline on a case in the dashboard and let you write session-scoped rules (e.g. velocity within a single session).

How to associate events

Generate a sessionId when a user session begins (typically at login or app open) and send it on every event that belongs to that visit. There are two placements, and they serve different purposes:

• metadata.sessionId — required for events to be grouped into a session on the dashboard timeline.
• Top-level sessionId — accepted on POST /api/v1/events and used for session-scoped rule evaluation at ingest time.

Send the same value in both places so the session drives both rules and the timeline.

Example: two events in one session

Both events carry the same sessionId and the same customer, so they appear together as one session on the customer's timeline.

1 — Login

POST /api/v1/events

{
  "eventName": "user.login",
  "eventCategory": "AUTHENTICATION",
  "customer": { "externalId": "user_123456" },
  "device": { "externalId": "device_abc123" },
  "ip": "203.0.113.42",
  "country": "SA",
  "sessionId": "session_xyz789",
  "metadata": {
    "sessionId": "session_xyz789",
    "auth_result": "success"
  }
}

2 — Payment in the same session

POST /api/v1/events

{
  "eventName": "payment.success",
  "eventCategory": "TRANSACTION",
  "customer": { "externalId": "user_123456" },
  "device": { "externalId": "device_abc123" },
  "ip": "203.0.113.42",
  "country": "SA",
  "sessionId": "session_xyz789",
  "metadata": {
    "sessionId": "session_xyz789",
    "amount": 250.0,
    "currency": "SAR"
  }
}

How sessions appear

On a case in the dashboard, events are grouped by session on the timeline and ordered by time within each session. Events sent without a metadata.sessionId are not dropped — they are collected under a single "No session" group so every event stays visible.

Best practices

• Use one stable sessionId for the life of a visit; start a new one on each fresh login.
• Never reuse a sessionId across different users or devices.
• Prefer an opaque, unguessable value (a UUID or random token), not a sequential counter.
• Keep the id out of anything customer-identifying — it is an opaque grouping key, not PII.