Sessions — Reference
The Sessions surface is the live-state plane for every SGEN site. It owns the record of who is currently authenticated, when their session started, when it was last active, which device or browser the session was opened from, and which network identity originated the request. Operations on this surface let an administrator end an active session (force-logout), configure the idle-timeout policy that ends sessions automatically, and review suspicious-activity flags raised by the platform's session-watching layer.
This page is a reference for platform engineers, integrators, and on-call support operators who need to understand the surface before extending it, scripting against it, or scoping a security policy. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Sessions live under the Sessions module in SG-Admin. The module renders three primary views — the active-sessions list, the per-operator session history, and the suspicious-activity log — and exposes write operations for force-logout (single session), force-logout-all (every session for a target operator), configure idle timeout, and configure suspicious-activity rules.
The module is paired by convention: one half renders the views and prepares the data, the other half handles writes and broadcasts session-end events to the rest of the platform. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
Sessions are related to but distinct from the Users surface. Users owns the operator record (identity, role, password); Sessions owns the active state derived from that record (which operators currently hold valid session tokens). A force-logout ends the session without touching the user record; a soft-delete of a user record from the Users surface also ends every active session for that user as a side effect.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Sessions
- URL prefix:
/sg-admin/sessions/ - View templates:
application/views/Admin/Sessions/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Sessions → Active │├──────────────────────────────────────────────────────────────────────┤│ Filter: [All operators ▾] Idle: [Any ▾] Flagged: [Any ▾] │├──────────────────────────────────────────────────────────────────────┤│ Operator Started Last seen Device State ││ ───────────── ────────── ────────── ─────────────── ──────── ││ Jerome Cruz 2h ago now Desktop · MNL Active ││ James Compton today 09:14 14m ago Mobile · NY Idle ││ Maria Reyes yesterday yesterday Desktop · MNL Stale ⚠ ││ Sandbox Operator 4 days ago 1h ago Desktop · NL Flagged⚠ ││ ││ [⋯ End session] [⋯ End all for operator] [⋯ Open history] │└──────────────────────────────────────────────────────────────────────┘Actions
The Sessions surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List active sessions
Returns every session that holds a valid token at the moment of the request, paginated, with operator, started-at, last-seen-at, device fingerprint, network origin, and state columns. State is one of active (recently seen), idle (within the idle-timeout window but no activity recently), stale (about to expire by idle policy), and flagged (raised by the suspicious-activity rules). Driven by the data-table contract used across SG-Admin modules.
Open per-operator session history
Filters the list down to a single operator and includes ended sessions in addition to active ones. Each row carries the same columns plus an end-state field (ended-by-logout, ended-by-timeout, ended-by-force, ended-by-user-delete). Used to answer "when did this operator most recently sign in" or "did someone force-end this operator's session this morning."
Force-logout a single session
Ends one named session. The targeted session's token is invalidated server-side; the next request that presents it is rejected as unauthenticated. The operator who held the session is not notified by the platform — surfaces that depend on real-time notification should wire a separate notification path. Force-logout writes an Activity Log entry.
Force-logout-all for an operator
Ends every active session for a named operator in one operation. Used in incident response — for example, when an operator's password has been changed because of suspected compromise, force-logout-all guarantees that any session opened with the old password no longer holds access. The operator can sign in again immediately with the new password.
Configure idle timeout
Sets the duration after which an inactive session is automatically ended. The setting is global per site and may be overridden per role through Settings. The value is enforced on the next request from the affected session — sessions that have been idle longer than the new threshold end immediately when their next request arrives.
View suspicious-activity log
Shows the events raised by the session-watching layer, paginated, with the operator, the rule that fired, the captured context, and the disposition (auto-ended, flagged-only, dismissed by administrator). Common rules include sign-in from a new network origin, multiple concurrent sessions from disparate geographies, and rapid succession of failed credentials before a successful sign-in.
Configure suspicious-activity rules
Sets which rules are enabled, the threshold at which each rule fires, and the disposition (flag-only or auto-end) per rule. Changes take effect immediately for new events; events already raised under the prior configuration are not reclassified.
Dismiss a flag
Marks a flagged event as reviewed without taking further action. Dismissed events remain in the log; they no longer surface in the default filtered view of the suspicious-activity log. Dismissal carries an operator identifier so the dismissing operator is recorded.
Data model
The Sessions surface manages two related record types. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
Session record:
| Field | Type | Notes |
|---|---|---|
id | string | Opaque session identifier. Stable across the lifetime of the session. |
operator_id | integer | Foreign key to the Users surface. |
started_at | timestamp | Set at sign-in, immutable. |
last_seen_at | timestamp | Touched on every authenticated request. |
device_fingerprint | string | Captured at sign-in. Browser plus operating system summary. |
network_origin | structured | Network identity and geographic resolution captured at sign-in. |
state | enum | active, idle, stale, flagged, ended. |
end_state | enum | Optional. Populated when state = ended. One of logout, timeout, force, user-delete. |
ended_at | timestamp | Optional. Set when the session ends. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
operator_id | integer | Subject of the event. |
session_id | string | Optional. The session that triggered the rule, if applicable. |
rule | string | Slug of the rule that fired. |
context | structured | Captured at fire time — comparison values, network details, prior session reference. |
disposition | enum | flag-only, auto-ended, dismissed. |
dismissed_by | integer | Optional. Operator who dismissed the flag. |
created_at | timestamp | Set on fire, immutable. |
Identity-resolution semantics: operator records resolved at display time, so a renamed operator shows their current name on past session rows. A deleted operator's session rows preserve the operator identifier and resolve to "deleted operator" at display time.
SIGN-IN ──▶ ACTIVE ──no activity──▶ IDLE ──nearing timeout──▶ STALE│ │ │ ││ │ │ ││ ▼ ▼ ▼│ FLAGGED ⚠ (timeout enforced on next request)│ (rule fired) ││ │ ││ │ ▼│ ▼ ENDED│ auto-ended (end_state = timeout)│ (per disposition)│ ││ ▼│ ENDED│ (end_state = force)│└──── logout / force-logout / user-delete ──▶ ENDEDPermissions
Access to the Sessions surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Sessions surface.
Layer 2 — per-action capability. Within SG-Admin, each Sessions action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List active sessions | ✔ | ✔ | — |
| Open per-operator session history | ✔ | ✔ | — |
| Force-logout single session | ✔ | — | — |
| Force-logout-all for an operator | ✔ | — | — |
| Configure idle timeout | ✔ | — | — |
| View suspicious-activity log | ✔ | ✔ | — |
| Configure suspicious-activity rules | ✔ | — | — |
| Dismiss a flag | ✔ | — | — |
Self-protection rules. An operator cannot force-end their own session through this surface (use the standard sign-out flow instead). The last remaining administrator on a site cannot be force-logged-out by another administrator unless a second administrator account is currently active. Suspicious-activity rules configured to auto-end sessions are exempt from the self-protection rule for the configuring operator — administrators can lock themselves out by mis-tuning a rule.
Audit. Every write — force-logout, force-logout-all, idle-timeout change, rule change, dismissal — emits an Activity Log entry. The log records the acting operator, the target (session identifier, operator identifier, or rule slug), and the change shape. Activity Log retention is governed by the site's general settings.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │ (custom roles override defaults)└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ self-force-logout / last-admin│ │ force-end → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry│▼session-end event(broadcast to platform listeners)Related references
- Users — Reference. Operator identifiers on session rows resolve through the Users surface. A soft-delete of a user ends every active session for that user as a side effect.
- Settings — Reference. Owns the role definitions, the global idle-timeout default, the per-role idle-timeout overrides, and the suspicious-activity event retention window.
- Tools — Reference. The Activity Log search surface lives under Tools; force-logout events and rule changes are findable there.
- Logs — Reference. Authentication failures, sign-in events, and session-end events surface on the auth channel for cross-referencing against Sessions records.
- Subscriptions — Reference. Seat-limit enforcement on the subscription tier may interact with the active-sessions count for sites that meter concurrent operator access.
- Pages — Reference. Pages that author content stamp the authoring operator on save; session state does not affect attribution but does affect whether the save is reached at all.
/docs/sessions.