Manage users server-side with the HelloJohn Node.js SDK — get, update, delete, and list users from your backend.

Users

The HelloJohn Node.js SDK provides a users namespace for managing users from your backend.

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

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

Get a User

const user = await hj.users.get("usr_01HABCDEF123456");

Or by email:

const user = await hj.users.getByEmail("jane@example.com");

User object:

interface User {
  id: string;
  email: string;
  emailVerified: boolean;
  firstName: string | null;
  lastName: string | null;
  phoneNumber: string | null;
  metadata: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
  lastSignInAt: Date | null;
  disabled: boolean;
}

List Users

const { users, nextCursor, total } = await hj.users.list({
  limit: 50,
  cursor: undefined, // pass nextCursor for pagination
});

// Filter
const { users: activeUsers } = await hj.users.list({
  status: "active",
  search: "@example.com",
});

Options:

Option	Type	Description
`limit`	`number`	Results per page (max: 100)
`cursor`	`string`	Pagination cursor
`search`	`string`	Search by email, name, or ID
`status`	`"active" \| "disabled"`	Filter by status
`orgId`	`string`	Filter by organization membership

Create a User

Create a user from your backend (skips email verification):

const user = await hj.users.create({
  email: "jane@example.com",
  password: "TemporaryPass123!",
  firstName: "Jane",
  lastName: "Doe",
  emailVerified: true, // Skip verification email
  metadata: {
    plan: "pro",
    source: "import",
  },
});

Update a User

await hj.users.update("usr_01HABCDEF123456", {
  firstName: "Jane",
  lastName: "Smith",
  metadata: {
    plan: "enterprise", // Merged with existing metadata
  },
});

Updatable fields: firstName, lastName, email, phoneNumber, avatarUrl, metadata, disabled.

Disable / Enable

// Disable (blocks sign-in, invalidates sessions)
await hj.users.disable("usr_01HABCDEF123456");

// Re-enable
await hj.users.enable("usr_01HABCDEF123456");

Delete a User

Permanently delete a user and all associated data:

await hj.users.delete("usr_01HABCDEF123456");

Impersonate a User

Get a session token for any user:

const { accessToken } = await hj.users.impersonate("usr_01HABCDEF123456", {
  reason: "Support ticket #4521",
  expiresIn: "1h",
});

Custom Metadata

Set and read arbitrary data on users:

// Write
await hj.users.update(userId, {
  metadata: {
    plan: "pro",
    trialEndsAt: "2024-12-31",
    featureFlags: { newDashboard: true },
  },
});

// Read
const user = await hj.users.get(userId);
const plan = user.metadata.plan as string;

Metadata is merged on update — partial updates do not remove existing keys. To remove a key, set it to null.

const exportData = await hj.users.export("usr_01HABCDEF123456");
// Returns full JSON with profile, sessions, MFA, OAuth connections, audit events

Users

On this page