User Sessions
Data Entity
Description
Active authentication sessions for users, tracking short-lived access tokens and rotating refresh tokens issued by the Authentication Module. Each session represents a single sign-in instance on a specific device and supports revocation (user sign-out, forced expiry, admin-initiated termination) and per-tenant isolation.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique session identifier (primary key). | PKrequiredunique |
user_id |
uuid |
Foreign key reference to the users table — the user owning the session. | required |
organization_id |
uuid |
Tenant scope for the session. Captured at sign-in for tenant isolation and audit. | - |
refresh_token_hash |
string |
Hashed value of the current rotating refresh token. Never store plaintext. | requiredunique |
access_token_jti |
string |
JWT ID claim of the most recently issued access token, used for revocation lookups. | - |
auth_method |
enum |
Authentication method used to establish this session. | required |
client_type |
enum |
Which Meander product the session belongs to. | required |
device_id |
string |
Stable per-device identifier (mobile installation ID or browser fingerprint). | - |
device_name |
string |
Human-readable device label (e.g., "iPhone 15 — Anne") shown in Session Management. | - |
user_agent |
text |
User-Agent string captured at session creation. | - |
ip_address |
string |
IP address observed at session creation / last refresh. | - |
issued_at |
datetime |
Timestamp when the session was created. | required |
last_refreshed_at |
datetime |
Timestamp of last successful refresh-token rotation. | - |
expires_at |
datetime |
Absolute expiry of the refresh token chain. After this the session is invalid even if not explicitly revoked. | required |
revoked_at |
datetime |
Timestamp when the session was revoked (sign-out, admin termination, refresh-chain break). Null while active. | - |
revocation_reason |
enum |
Reason the session was terminated. | - |
revoked_by_user_id |
uuid |
Admin user who revoked the session, if revocation was admin-initiated. | - |
biometric_unlocked |
boolean |
Whether biometric unlock (Face ID / fingerprint) is bound to this mobile session. | - |
claims |
json |
Generic claims bag (role, organization memberships) injected into issued tokens. Kept opaque to the Auth Module. | - |
created_at |
datetime |
Record creation timestamp. | required |
updated_at |
datetime |
Record last-modified timestamp. | required |
Database Indexes
idx_user_sessions_user_id
Columns: user_id
idx_user_sessions_refresh_token_hash
Columns: refresh_token_hash
idx_user_sessions_organization_id
Columns: organization_id
idx_user_sessions_expires_at
Columns: expires_at
idx_user_sessions_active
Columns: user_id, revoked_at, expires_at
Validation Rules
expires_after_issued
error
Validation failed
refresh_token_hash_present
error
Validation failed
valid_auth_method
error
Validation failed
revocation_consistency
error
Validation failed
user_exists
error
Validation failed
active_session_lookup
info
Validation failed
Business Rules
tenant_isolation
A session's organization_id, when present, must match the owning user's active organization scope. Cross-tenant token use is rejected.
refresh_token_rotation
Each refresh issues a new refresh_token_hash and invalidates the prior value. Reuse of a retired refresh token breaks the chain and revokes the session.
admin_initiated_revocation
Org Admins may revoke any active session within their organization; Global Admins may revoke sessions across organizations only when support-access flag is active.
password_change_revokes_sessions
Changing the user's password revokes all active sessions for that user with reason password_changed.
biometric_only_on_mobile
biometric_unlocked may only be true when client_type = mobile_app.
audit_session_lifecycle
Session creation and revocation events are written to the organization audit log.