Sessions
Data Entity
Description
Tracks authenticated user sessions across devices and platforms, storing device metadata, IP addresses, login timestamps, and session lifecycle state. Enables administrators to monitor active sessions, detect anomalous login patterns, and revoke sessions for security incident response or user offboarding.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique session identifier, generated server-side on login | PKrequiredunique |
user_id |
uuid |
Foreign key to users table identifying the authenticated user | required |
device_type |
enum |
Type of device used to establish the session | required |
device_name |
string |
Human-readable device identifier (e.g. 'iPhone 15 Pro', 'Chrome on Windows') | - |
ip_address |
string |
IP address at session creation, stored for security monitoring and audit | required |
user_agent |
text |
Full User-Agent header string from the login request | - |
auth_method |
enum |
Authentication method used to establish this session | required |
organization_id |
uuid |
Organization context for the session, derived from user account at login | - |
active_role_id |
uuid |
The role active at session creation or last role switch | - |
status |
enum |
Current lifecycle state of the session | required |
created_at |
datetime |
Timestamp when the session was established (login time) | required |
last_activity_at |
datetime |
Timestamp of the most recent authenticated request on this session | required |
expires_at |
datetime |
Absolute session expiry time, after which the session is invalid regardless of activity | required |
revoked_at |
datetime |
Timestamp when the session was manually revoked by admin or user logout | - |
revoked_by |
uuid |
User ID of the administrator or user who revoked this session | - |
revocation_reason |
enum |
Reason for session termination when manually revoked | - |
Database Indexes
idx_sessions_user_id
Columns: user_id
idx_sessions_user_status
Columns: user_id, status
idx_sessions_organization_id
Columns: organization_id
idx_sessions_status_expires
Columns: status, expires_at
idx_sessions_created_at
Columns: created_at
idx_sessions_last_activity_at
Columns: last_activity_at
Validation Rules
valid_user_reference
error
Validation failed
valid_ip_format
error
Validation failed
expires_at_future
error
Validation failed
revocation_fields_consistency
error
Validation failed
status_transition_validity
error
Validation failed
last_activity_monotonic
error
Validation failed
organization_matches_user
error
Validation failed
Business Rules
one_active_session_per_device
When a user logs in from the same device type, any existing active session for that device is marked as expired to prevent session accumulation
absolute_session_expiry
Sessions have a maximum absolute lifetime (e.g. 30 days for mobile, 24 hours for web) regardless of activity. Expired sessions cannot be refreshed — user must re-authenticate
idle_session_timeout
Sessions with no activity for a configurable period (e.g. 30 minutes for web admin, 7 days for mobile) transition to idle status and require re-authentication
cascade_revoke_on_deactivation
When a user account is deactivated via admin portal, all active sessions for that user must be immediately revoked
revoke_on_password_change
When a user changes their password, all sessions except the current one must be revoked to invalidate potentially compromised sessions
revoke_on_role_change
When user roles are modified, existing sessions should be revoked so the user re-authenticates and receives updated JWT claims
tenant_scoped_session_visibility
Organization admins can only view and revoke sessions belonging to users within their organization. Global admins can see sessions across organizations but without user content access
audit_all_revocations
Every session revocation must generate an audit log entry recording who revoked it, the reason, and the affected user
concurrent_session_limit
Configurable maximum number of concurrent active sessions per user (default: 5). When exceeded, the oldest session is automatically revoked