---
title: "Sessions"
description: "Session grouping and timeline endpoints."
collection: "api-reference"
slug: "sessions"
url: "https://naiza.ai/docs/api-reference/sessions"
markdown: "https://naiza.ai/docs/api-reference/sessions.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Sessions

> Session grouping and timeline endpoints.

## Table of contents

- [How to associate events](#how-to-associate-events)
- [Example: two events in one session](#example-two-events-in-one-session)
  - [1 — Login](#1-login)
  - [2 — Payment in the same session](#2-payment-in-the-same-session)
- [How sessions appear](#how-sessions-appear)
- [Best practices](#best-practices)

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

```http
POST /api/v1/events
```

```json
{
  "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

```json
{
  "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.

## Related documentation

- [API Overview](https://naiza.ai/docs/api-reference/overview.md) — Base URL, versioning, and high-level API surface.
- [Authentication](https://naiza.ai/docs/api-reference/authentication.md) — API keys, Web SDK tokens, and secure key handling.
- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md) — Browser SDK endpoints and device signal collection.
- [Events API](https://naiza.ai/docs/api-reference/events.md) — Submit and query product events for risk evaluation.
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md) — Error shapes, status codes, and retry guidance.
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md) — Quota headers and rate-limit behavior.
- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md) — approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).
- [Lists API](https://naiza.ai/docs/api-reference/lists.md) — Allowlists, blocklists, and list membership management.

---

*Source: [https://naiza.ai/docs/api-reference/sessions](https://naiza.ai/docs/api-reference/sessions) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*