Session Management¶
The Grit SDK provides a session management system that tracks authenticated user sessions, monitors activity, and allows users to manage their signed-in devices. It has per-session metadata such as device info, IP address, and last-active timestamps.
Overview¶
| Lifecycle Stage | What happens |
|---|---|
| Creation | A UserSession record is automatically created when a user logs in |
| Activity tracking | last_active_at is updated on each request (throttled to every 15 minutes) |
| Device overview | Users can view all their active sessions grouped by device |
| Sign-out | Users can terminate a specific session or all other sessions |
| Cleanup | A management command removes stale signed-out records |
Data Models¶
UserSession¶
Tracks metadata for each authenticated session.
Fields:
| Field | Type | Description |
|---|---|---|
id |
UUIDField |
Primary key (auto-generated) |
user |
ForeignKey(CustomUser) |
The authenticated user. Reverse accessor: user.sessions |
user_agent |
CharField(max_length=512) |
Raw User-Agent header captured at login |
ip |
GenericIPAddressField |
Client IP address at login. Nullable |
status |
CharField |
Current state — see Status below |
last_active_at |
DateTimeField |
Most recent request timestamp. Nullable |
signed_out_at |
DateTimeField |
When the session was terminated. Nullable |
metadata |
JSONField |
Arbitrary key-value data. Nullable |
created_at |
DateTimeField |
Record creation time (auto-set) |
updated_at |
DateTimeField |
Last modification time (auto-set) |
Default ordering: -last_active_at (most recently active first).
UserSession.Status¶
class Status(models.TextChoices):
ACTIVE = "active", "Active"
SIGNED_OUT = "signed_out", "Signed out"
UserSession.sign_out()¶
Terminates this session. Invalidates the user's cookie so subsequent requests are unauthenticated, sets status to SIGNED_OUT, and records the signed_out_at timestamp.
Session Tracking¶
Automatic Session Creation¶
A UserSession record is automatically created each time a user logs in. The record captures the user's IP address and User-Agent at the time of login.
If a user logs in again on the same browser session, the existing record is updated rather than duplicated.
It keeps last_active_at up to date on authenticated requests. Updates are throttled to once every 15 minutes to minimize database writes.
Device Management Views¶
All views require the user to be authenticated.
Device List¶
Displays all sessions for the current user, grouped by device type (computer, phone, tablet) and operating system.
| Detail | Value |
|---|---|
| URL name | device_list |
| Method | GET |
| Template | customauth/devices.html |
Each session entry includes: - Device label (e.g., "Chrome on macOS") - Whether it is the current session - Number of inactive days
Sign Out a Session¶
Terminates a specific remote session by its ID.
| Detail | Value |
|---|---|
| URL name | sign_out_session |
| Method | POST |
| Parameter | session_id (UUID) |
Users cannot sign out their own current session from this view — they should use the regular sign-out flow instead.
Sign Out All Other Sessions¶
Terminates all active sessions except the current one.
| Detail | Value |
|---|---|
| URL name | sign_out_all_other_sessions |
| Method | POST |
Management Commands¶
cleanup_sessions¶
Deletes UserSession records that have been in SIGNED_OUT status for longer than a specified retention period.
Arguments:
| Flag | Default | Description |
|---|---|---|
--days |
28 |
Delete signed-out sessions older than this many days |
--dry-run |
off | Preview what would be deleted without making changes |
Examples: