Active Sessions & Instant Revocation

Track active devices, inspect client IPs, and execute instant remote signouts across web, mobile, and API clients.

Dual-layer session architecture

Stateless JWT tokens present a well-known security challenge: once signed, a JWT cannot be invalidated until its expiration timestamp without a revocation mechanism. If an end-user loses their laptop or their token is compromised, waiting 15 to 60 minutes for token expiration is an unacceptable security window.

HVT solves this with a dual-layer session architecture:

  1. Persistent Database Layer: Every authentication event creates a UserSession record in PostgreSQL. This stores client IP addresses, parsed device names (e.g. "Chrome on macOS", "Safari on iPhone"), User-Agent headers, creation dates, and throttled last-active timestamps.
  2. Sub-Millisecond Redis Cache Layer: Active sessions are registered in Redis under session:active:<sid>. When a session is revoked, HVT immediately deletes the active key and writes to session:revoked:<sid> with a 7-day TTL matching refresh token lifetimes.

Session management API endpoints

HVT exposes dedicated endpoints for both end-users (runtime plane) and organization administrators (control plane):

Method & PathDescriptionScope
GET /api/v1/auth/runtime/sessions/List active sessions and devices for the calling runtime user.End-User
DELETE /api/v1/auth/runtime/sessions/<id>/Instantly revoke a specific session by UUID.End-User
POST /api/v1/auth/runtime/sessions/revoke-all/Revoke all sessions except the current caller ("Log out everywhere else").End-User
GET /api/v1/auth/sessions/Control-plane equivalent for organization team members and developers.Platform User

Listing active sessions returns device metadata and highlights the current caller:

json
// GET /api/v1/auth/runtime/sessions/
[
  {
    "id": "c2a1b0d9-e8f7-4a6b-9c5d-3e2f1a0b9c8d",
    "project": "b5540592-38fd-4d42-9538-c125716f31f4",
    "ip_address": "198.51.100.42",
    "device_name": "Chrome on macOS",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...",
    "created_at": "2026-11-09T08:30:00Z",
    "last_active_at": "2026-11-09T10:15:22Z",
    "is_current": true
  },
  {
    "id": "7f8e9d0c-1b2a-4c5e-8f9a-0b1c2d3e4f5a",
    "project": "b5540592-38fd-4d42-9538-c125716f31f4",
    "ip_address": "203.0.113.19",
    "device_name": "Safari on iPhone",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X)...",
    "created_at": "2026-11-07T14:12:00Z",
    "last_active_at": "2026-11-08T19:40:11Z",
    "is_current": false
  }
]

Revoking a specific remote device:

bash
# Revoke a specific session by UUID
DELETE /api/v1/auth/runtime/sessions/7f8e9d0c-1b2a-4c5e-8f9a-0b1c2d3e4f5a/
Authorization: Bearer <user_access_token>
X-API-Key: <project_client_or_server_key>

# Response (200 OK)
{
  "detail": "Session revoked successfully."
}

Executing global remote logout across all other devices:

bash
# Revoke all other sessions except the current caller
POST /api/v1/auth/runtime/sessions/revoke-all/
Authorization: Bearer <user_access_token>
X-API-Key: <project_client_or_server_key>

# Response (200 OK)
{
  "detail": "All other sessions have been revoked.",
  "revoked_count": 3
}

Hybrid verification pattern

For maximum performance, downstream services verify RS256 token signatures locally via JWKS on every request. To enforce instant revocation, services can perform an ultra-fast Redis check against session:revoked:<sid>:

python
# Python / FastAPI: Hybrid Verification (JWKS + Selective Session Check)
import os
import redis
import jwt
from jwt import PyJWKClient
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

security = HTTPBearer()
r = redis.Redis.from_url(os.getenv("REDIS_URL", "redis://localhost:6379/0"))
jwks_client = PyJWKClient(f"{os.getenv('HVT_API_URL')}/.well-known/jwks.json")

async def get_current_user_and_session(credentials: HTTPAuthorizationCredentials = Depends(security)):
    token = credentials.credentials
    # 1. Fast path: Verify cryptographic signature locally
    signing_key = jwks_client.get_signing_key_from_jwt(token)
    claims = jwt.decode(token, signing_key.key, algorithms=["RS256"])

    sid = claims.get("sid")
    if sid:
        # 2. Sub-millisecond Redis check: Is this session explicitly revoked?
        if r.exists(f"session:revoked:{sid}"):
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="Session has been revoked.",
            )

    return claims
Tiered Security Strategy
For standard read-only API requests, local JWKS verification is sufficient. For critical write operations (e.g. changing passwords, updating billing, transferring ownership), always query session revocation to guarantee immediate enforcement.

Frontend device manager component

A ready-to-use React component for user account settings, displaying active sessions and providing one-click revocation:

tsx
import React, { useEffect, useState } from 'react';
import { Laptop, Smartphone, Trash2, ShieldAlert } from 'lucide-react';

export function ActiveSessionsManager({ apiBaseUrl, accessToken, apiKey }) {
  const [sessions, setSessions] = useState([]);
  const [loading, setLoading] = useState(true);

  const fetchSessions = async () => {
    try {
      const res = await fetch(`${apiBaseUrl}/api/v1/auth/runtime/sessions/`, {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'X-API-Key': apiKey,
        },
      });
      const data = await res.json();
      setSessions(data);
    } finally {
      setLoading(false);
    }
  };

  const handleRevoke = async (id) => {
    await fetch(`${apiBaseUrl}/api/v1/auth/runtime/sessions/${id}/`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'X-API-Key': apiKey,
      },
    });
    setSessions((prev) => prev.filter((s) => s.id !== id));
  };

  const handleRevokeAllOther = async () => {
    await fetch(`${apiBaseUrl}/api/v1/auth/runtime/sessions/revoke-all/`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'X-API-Key': apiKey,
      },
    });
    setSessions((prev) => prev.filter((s) => s.is_current));
  };

  useEffect(() => {
    fetchSessions();
  }, []);

  if (loading) return <p>Loading active devices...</p>;

  return (
    <div className="space-y-4">
      <div className="flex items-center justify-between">
        <h3 className="text-lg font-semibold text-white">Active Devices</h3>
        <button
          onClick={handleRevokeAllOther}
          className="text-sm text-red-400 hover:text-red-300"
        >
          Sign out all other devices
        </button>
      </div>

      <div className="divide-y divide-zinc-800">
        {sessions.map((session) => (
          <div key={session.id} className="py-3 flex items-center justify-between">
            <div className="flex items-center gap-3">
              {session.device_name.includes('iPhone') || session.device_name.includes('Android') ? (
                <Smartphone className="w-5 h-5 text-zinc-400" />
              ) : (
                <Laptop className="w-5 h-5 text-zinc-400" />
              )}
              <div>
                <p className="font-medium text-white">
                  {session.device_name}
                  {session.is_current && (
                    <span className="ml-2 px-2 py-0.5 text-xs bg-emerald-950 text-emerald-400 rounded">
                      This Device
                    </span>
                  )}
                </p>
                <p className="text-xs text-zinc-400">
                  IP: {session.ip_address} • Last active: {new Date(session.last_active_at).toLocaleString()}
                </p>
              </div>
            </div>

            {!session.is_current && (
              <button
                onClick={() => handleRevoke(session.id)}
                className="p-1.5 text-zinc-400 hover:text-red-400"
                aria-label={`Revoke session for ${session.device_name}`}
              >
                <Trash2 className="w-4 h-4" />
              </button>
            )}
          </div>
        ))}
      </div>
    </div>
  );
}