User Session
Data Entity
Description
Represents an authenticated user session storing JWT tokens and expiry metadata for persistent login. Sessions enable biometric re-authentication on app resume without requiring full credential re-entry. Stored in encrypted platform secure storage (flutter_secure_storage via Keychain/Keystore) and synced with Supabase Auth as the authoritative session store.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique session identifier. Matches the Supabase Auth session ID returned by GoTrueClient. Used as the primary lookup key in local secure storage. | PKrequiredunique |
user_id |
uuid |
Foreign key referencing the authenticated user. Used to scope session data to the correct account and to resolve roles and organization memberships after biometric re-authentication. | required |
access_token |
string |
Supabase Auth JWT access token. Signed by Supabase with HS256 or RS256. Stored encrypted in platform secure storage. Included in Authorization header for all Supabase API and Edge Function calls. Short-lived — typically 1 hour. | required |
refresh_token |
string |
Opaque Supabase Auth refresh token. Used by supabase-session-manager to obtain a new access token before expiry. Stored encrypted in platform secure storage. Longer-lived than the access token. | requiredunique |
expires_at |
datetime |
UTC timestamp at which the access token expires. Evaluated by session-resume-manager on every AppLifecycleState.resumed event to decide whether to trigger biometric prompt or redirect to full credential login. | required |
refresh_token_expires_at |
datetime |
UTC timestamp at which the refresh token expires. When this is in the past the full login flow must be repeated regardless of biometric availability. May be null for sessions where Supabase does not expose refresh token lifetime. | - |
biometric_enabled |
boolean |
Whether the user has opted in to biometric re-authentication for this session on this device. Set to true only after the user completes an explicit biometric enrollment confirmation. Defaults to false. | required |
biometric_enrolled_at |
datetime |
UTC timestamp when biometric opt-in was confirmed for this session. Used in audit trails and to detect whether a device biometric re-enrollment has occurred since the preference was saved. | - |
device_id |
string |
Platform device identifier (e.g., iOS identifierForVendor, Android ANDROID_ID). Used to associate the session with a specific device, enabling per-device biometric preferences and supporting multi-device session management. | - |
platform |
enum |
Mobile platform on which the session was created. Determines which biometric API is used (local_auth maps to Face ID/Touch ID on iOS, Fingerprint/Face on Android) and which secure storage backend is active. | required |
organization_id |
uuid |
The organization context active when this session was established. Injected as the app.current_org_id Supabase session variable for RLS enforcement. Updated on organization switch without re-authentication. | - |
created_at |
datetime |
UTC timestamp when the session was first persisted to local secure storage after a successful authentication event (email/password, BankID, or Vipps). | required |
last_resumed_at |
datetime |
UTC timestamp of the most recent successful biometric re-authentication on app resume. Updated by session-resume-manager each time a biometric challenge succeeds. Null if biometric has never been used for this session. | - |
is_active |
boolean |
Whether this session is currently active. Set to false on explicit logout, access token refresh failure, or refresh token expiry. Local secure storage entry is deleted when false; field exists to enable graceful cleanup coordination. | required |
Database Indexes
idx_session_user_id
Columns: user_id
idx_session_expires_at
Columns: expires_at
idx_session_user_device
Columns: user_id, device_id
idx_session_refresh_token
Columns: refresh_token
Validation Rules
access_token_jwt_format
error
Validation failed
expires_at_is_future_on_create
error
Validation failed
refresh_token_present_with_access_token
error
Validation failed
biometric_enrolled_at_set_with_flag
error
Validation failed
user_id_non_empty
error
Validation failed
refresh_token_uniqueness
error
Validation failed
platform_enum_valid
error
Validation failed
refresh_token_expiry_ordering
error
Validation failed
Business Rules
single_session_per_device
Each user may have at most one active session per physical device (unique composite of user_id + device_id). When a new session is created on a device that already has an active session for the same user, the previous session is overwritten in secure storage.
proactive_token_refresh
The access token must be refreshed before expiry to maintain uninterrupted API access. supabase-session-manager monitors token lifetime and initiates refresh at least 60 seconds before expires_at.
biometric_requires_valid_session
Biometric re-authentication is only permitted when the refresh token has not expired. If refresh_token_expires_at is in the past, the user must complete full credential login regardless of biometric_enabled state.
biometric_opt_in_explicit
biometric_enabled may only be set to true after an explicit user confirmation interaction. It must never be defaulted to true or set programmatically without a user-initiated enrollment step. biometric_enrolled_at must be recorded simultaneously.
session_cleared_on_logout
On any logout event (explicit user action, token refresh failure, or server-side revocation), the session record must be completely removed from local secure storage and the Supabase Auth sign-out endpoint must be called to invalidate the refresh token server-side.
organization_scope_maintained
The organization_id stored in the session must match the active RLS tenant scope configured via supabase-rls-tenant-configurator. If a user switches organization context, organization_id is updated in the session and the Supabase client session variable is refreshed without requiring re-authentication.
biometric_cleared_on_device_biometric_change
If the device reports a change in biometric enrollment (e.g., new fingerprint added), biometric_enabled must be reset to false and the user must re-confirm biometric opt-in. This prevents unauthorized biometric access after a device owner change.
multi_device_session_isolation
Sessions on different devices for the same user are fully independent. Logout on one device does not invalidate sessions on other devices unless a server-side global sign-out is explicitly triggered. Each device maintains its own secure storage.
CRUD Operations
Storage Configuration
Entity Relationships
A user may have multiple active sessions across different devices for biometric re-authentication