Manage user sessions server-side with the HelloJohn Node.js SDK — list, revoke, and inspect sessions.

Sessions

The sessions namespace provides server-side management of user sessions.

import { HelloJohn } from "@hellojohn/node";

const hj = new HelloJohn({
  tenantId: process.env.HELLOJOHN_TENANT_ID!,
  secretKey: process.env.HELLOJOHN_SECRET_KEY!,
});

Get a Session

const session = await hj.sessions.get("ses_01HABCDEF123456");

Session object:

interface Session {
  id: string;
  userId: string;
  createdAt: Date;
  lastActiveAt: Date;
  expiresAt: Date;
  refreshExpiresAt: Date;
  ipAddress: string | null;
  userAgent: string | null;
  deviceFingerprint: string | null;
  revoked: boolean;
  revokedAt: Date | null;
}

List Sessions for a User

const { sessions } = await hj.sessions.list("usr_01HABCDEF123456");

// Active sessions only
const { sessions: active } = await hj.sessions.list("usr_01HABCDEF123456", {
  status: "active",
});

Revoke a Session

Force sign-out a specific session:

await hj.sessions.revoke("ses_01HABCDEF123456");

After revocation:

The refresh token becomes invalid immediately
The access token remains valid until it expires (up to 15 minutes)
For immediate access token invalidation, use API-based verification

Revoke All Sessions for a User

Force sign-out all devices:

await hj.sessions.revokeAll("usr_01HABCDEF123456");

Use this after:

Password reset
Suspected account compromise
User account disable

Verify Session

Check if a session ID is still valid (API-based, real-time):

const { valid, session } = await hj.sessions.verify("ses_01HABCDEF123456");

if (!valid) {
  // Session has expired or been revoked
}

Use Cases

Force Sign-Out on Password Change

async function changePassword(userId: string, newPassword: string) {
  // Update password...
  await hj.users.update(userId, { password: newPassword });

  // Revoke all existing sessions to force re-authentication
  await hj.sessions.revokeAll(userId);
}

Detect Suspicious Sessions

const { sessions } = await hj.sessions.list(userId);

// Flag sessions from unusual locations
const unusualSessions = sessions.filter(
  (s) => s.ipAddress && !isTrustedIP(s.ipAddress)
);

Sessions

On this page