Portal Session Management

The Cloud Portal tracks active sessions for each organization administrator. Session management lets admins see where they are logged in, revoke suspicious sessions, and perform bulk logout for security events like employee offboarding.

Every time an administrator authenticates, the Portal creates a database session record tied to the issued JWT. The session record persists independently of the JWT’s expiry, giving you the ability to invalidate credentials immediately — without waiting for the token to expire on its own.

---

What Is Tracked Per Session

Each active session exposes the following fields:

Field	Description
session_id	Unique identifier for this session (embedded in the JWT)
user_agent	Browser/client user agent string captured at login time
ip_address	IP address used when the session was created
created_at	Timestamp when the session was established
last_active_at	Timestamp of the last API call made using this session’s JWT
is_current	Boolean — true if this is the session making the request

Note

The session_id is embedded in the JWT at login time. Each JWT maps to exactly one database session record. Revoking the database session invalidates the JWT even if it hasn’t expired yet.

---

Viewing Active Sessions

Portal UI

Navigate to Account > Sessions at /portal/account/sessions to see all active sessions for your user account.

Each row in the session list displays:

• Client — the user agent parsed to a friendly name, such as “Chrome on macOS” or “Firefox on Windows”
• IP Address — the originating IP address captured at login
• Created — when the session was established
• Last Active — when the session last made an authenticated API call

The session corresponding to your current request is highlighted with a Current badge. This session cannot be revoked from the session management page — see Revoking Individual Sessions below.

API

GET /v1/orgs/{org_id}/sessions

Returns an array of OrgAdminSession objects for the authenticated user. Sessions from other users in the organization are not included — each admin can only see their own sessions.

Example response:

{
  "sessions": [
    {
      "session_id": "sess_a1b2c3d4",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "ip_address": "203.0.113.42",
      "created_at": "2026-03-15T09:00:00Z",
      "last_active_at": "2026-03-15T14:30:00Z",
      "is_current": true
    },
    {
      "session_id": "sess_e5f6g7h8",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
      "ip_address": "198.51.100.17",
      "created_at": "2026-03-14T11:00:00Z",
      "last_active_at": "2026-03-14T16:45:00Z",
      "is_current": false
    }
  ]
}

---

Revoking Individual Sessions

Portal UI

Click the Revoke button on any session row in the session list. The current session row does not show a Revoke button — you cannot revoke the session you are actively using through this interface.

API

DELETE /v1/orgs/{org_id}/sessions/{session_id}

Immediately removes the database session record for the given session_id.

Behavior:

• Returns 204 No Content on success.
• Returns 400 Bad Request if session_id refers to the current session. Use the bulk revoke endpoint or the standard log out flow to end your own session.
• The revoked session’s JWT is immediately invalidated. Any subsequent API call using that JWT returns 401 Unauthorized, regardless of the token’s embedded expiry time.
• A session.revoked audit event is written to the organization audit log.

Caution

You cannot revoke your current session through the session management page. To end your current session, use the standard “Log out” option in the user menu. This ensures you are cleanly signed out rather than leaving your browser in an inconsistent state.

---

Revoke All Other Sessions

The Revoke all other sessions action (labeled “Log out everywhere” in the Portal UI) terminates every session except the one you are currently using. Your current session remains active so you do not lose access mid-operation.

Portal UI

The Revoke all other sessions button appears at the top of the session list at /portal/account/sessions. Clicking it presents a confirmation dialog before proceeding.

API

DELETE /v1/orgs/{org_id}/sessions

No session_id path parameter. The server identifies the current session from the bearer token and excludes it from revocation automatically.

Behavior:

• Returns 204 No Content on success, even if no other sessions existed.
• All other sessions are revoked atomically.
• Creates a single session.revoked_all audit event — not one event per session revoked.
• JWTs belonging to all revoked sessions return 401 on their next use.

Common use cases:

• Cleaning up after using a shared or public workstation
• Responding to a suspected credential compromise
• Offboarding a departing administrator

---

When to Revoke Sessions

Suspicious Login from an Unknown IP

If you notice a session originating from an IP address you do not recognize, revoke it immediately. After revoking, check the Account Security Monitor for additional anomalous activity that may have occurred during the session’s lifetime.

If the unfamiliar IP belongs to a corporate VPN or egress NAT gateway you were not aware of, you can confirm that in the security monitor before taking further action.

Shared Workstation

After using a shared or public computer — such as a hotel business center, a conference room terminal, or a colleague’s machine — revoke that session remotely from your primary device. Even if you closed the browser, the JWT remains valid until it expires or the session is explicitly revoked.

Employee Offboarding

When an administrator leaves the organization, an org_admin should:

1. Navigate to the departing admin’s account in the Admin Users panel.
2. Revoke all their active sessions (via the API or by acting on their behalf if you have sufficient privilege).
3. Remove the user from the organization or downgrade their role to prevent re-authentication.

Revoking sessions alone is not sufficient for offboarding — the user could log in again if their credentials are intact. Session revocation and role removal should be performed together.

Tip

Automating offboarding via the API ensures sessions are revoked and roles are updated atomically. Refer to the Admin User Management guide for the full offboarding sequence.

Compromised Credentials

If you suspect your password has been leaked or phished:

1. Use Revoke all other sessions immediately to terminate any attacker-held sessions.
2. Reset your password.
3. Review the security monitor for any actions taken during the suspect session window.
4. If sensitive data was accessed, notify your organization’s security contact.

---

GeoIP Context

The session list displays the raw IP address captured at login. It does not show geographic location data inline.

GeoIP enrichment is only available in the Account Security Monitor, which is a separate feature. The security monitor correlates session IPs with GeoIP databases for anomaly detection — for example, flagging a login from a country where the user has never authenticated before.

If you need to verify where a login originated geographically, check the security monitor rather than attempting to look up the IP address manually. The monitor also retains historical session context that the active session list does not.

---

Integration with the Account Security Monitor

Session management and the Account Security Monitor are complementary features that share the same underlying event stream.

Event	Trigger	Visible In
session.created	Successful login	Security monitor
session.revoked	Single session revoked	Audit log, security monitor
session.revoked_all	Bulk revoke executed	Audit log, security monitor
session.expired	Database session purged after inactivity	Audit log

What the security monitor adds beyond the session list:

• GeoIP enrichment on session origin IPs
• Anomaly detection (unusual IP range, unexpected user agent pattern, login velocity)
• Timeline correlation — viewing session activity alongside other admin actions
• security_alert notifications when anomalous session properties are detected

Security monitor alerts are delivered as security_alert notifications. Refer to the Portal Notifications guide for how to configure notification delivery (email, webhook, in-app).

Note

The security monitor does not revoke sessions automatically, even when it flags anomalous activity. Revocation always requires an explicit admin action, ensuring you retain full control over access decisions.

---

Session Expiry and JWT Validation

How JWT Expiry and Database Sessions Interact

JWTs carry a built-in expiry timestamp (exp claim), configured server-side. The default expiry is 24 hours from issuance. However, JWT expiry alone is not the only gate on a request.

Validation flow for every authenticated API call:

1. The server validates the JWT signature and checks the exp claim.
2. The server extracts the session_id embedded in the JWT payload.
3. The server looks up that session_id in the database.
4. If the session record does not exist or is marked revoked, the server returns 401 Unauthorized — regardless of the JWT’s exp value.

This two-layer check means that revoking a session in the database immediately invalidates the JWT, even if it has hours of validity remaining.

Automatic Session Cleanup

Database sessions that have been inactive for more than 30 days are purged automatically by a background cleanup job. Purged sessions generate a session.expired audit event. Once purged, the corresponding JWT returns 401 on its next use, exactly as a manually revoked session would.

This cleanup prevents the session list from accumulating stale records indefinitely and ensures that rarely-used long-lived tokens cannot remain active beyond the inactivity window.

Note

JWT expiry and session revocation are independent mechanisms. Even if a JWT has 23 hours remaining on its exp claim, revoking the database session immediately prevents that JWT from being used for any subsequent request.

Summary of Invalidation Paths

Condition	JWT Accepted?
JWT not yet expired, session active	Yes
JWT expired, session active	No — 401, token expired
JWT not yet expired, session revoked	No — 401, session not found
JWT not yet expired, session purged (30-day inactivity)	No — 401, session not found

---

API Reference

The following endpoints support session management. Authentication requires a valid org JWT with any role — sessions are always filtered to the currently authenticated user, regardless of role.

Method	Path	Description
GET	/v1/orgs/{org_id}/sessions	List all active sessions for the current user
DELETE	/v1/orgs/{org_id}/sessions/{session_id}	Revoke a specific session by ID (400 if current)
DELETE	/v1/orgs/{org_id}/sessions	Revoke all sessions except the current one

Path parameters:

Parameter	Type	Description
org_id	string	The organization identifier
session_id	string	The session identifier (format: sess_*)

Authorization: All three endpoints require a valid bearer token issued to a Portal admin account belonging to the specified org_id. No elevated role is required — any authenticated admin can manage their own sessions.

Full request and response schemas are documented in the API Batch 32 reference.

---

Related Guides

• Account Security Monitor — GeoIP enrichment, anomaly detection, and security alert configuration
• Portal Notifications — Configuring delivery channels for security_alert events
• Admin User Management — Full offboarding sequence including role removal
• Portal RBAC — Role definitions and permission scopes for org admins