HelloJohn / docs
Users

Admin User Management

List, search, impersonate, disable, and ban users from the admin plane in HelloJohn.

Admin User Management

Admin operations on users require a secret key (sk_live_) with the appropriate scope. These endpoints bypass user-level restrictions and are intended for backend admin tooling only.

List All Users

curl "https://api.hellojohn.dev/v1/users?limit=50" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Query Parameters

ParameterDescription
limitResults per page (default: 20, max: 100)
cursorPagination cursor
order_bycreated_at (default) or email
directionasc or desc

Search users by any field using the admin search endpoint:

curl -X POST "https://api.hellojohn.dev/v1/admin/users/search" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "alice",
    "filters": {
      "mfa_enrolled": true,
      "disabled": false,
      "created_after": "2024-01-01T00:00:00Z",
      "organization_id": "org_01HABCDEF777666"
    },
    "limit": 25
  }'

Search Filters

FilterTypeDescription
querystringFull-text search on name and email
mfa_enrolledbooleanFilter users with/without MFA
disabledbooleanFilter active or disabled users
created_afterISO timestampUsers created after date
created_beforeISO timestampUsers created before date
organization_idstringUsers belonging to an org
rolestringFilter by system role

Impersonate a User

Generate a session token for any user without their credentials. Useful for debugging and support.

curl -X POST "https://api.hellojohn.dev/v1/admin/users/impersonate" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_01HABCDEF123456",
    "reason": "Support ticket #8842 — user cannot access dashboard",
    "expires_in": "1h"
  }'

Response:

{
  "access_token": "eyJhbGciOiJFZERTQSJ9...",
  "session_id": "ses_01HABCDEF_impersonate",
  "impersonated_user_id": "usr_01HABCDEF123456",
  "expires_at": "2024-01-20T11:00:00Z"
}
  • The resulting session is marked impersonated: true in the audit log
  • The reason field is required and logged for compliance
  • Impersonation sessions are short-lived (max 24h)
  • Impersonation is always logged in the audit trail

Disable a User

Disabling prevents sign-in and revokes all active sessions:

curl -X PATCH "https://api.hellojohn.dev/v1/users/usr_01HABCDEF123456" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{"disabled": true}'

To disable and revoke all sessions in one call:

curl -X PATCH "https://api.hellojohn.dev/v1/users/usr_01HABCDEF123456" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{"disabled": true, "revoke_sessions": true}'

Re-enable with "disabled": false.

Bulk Disable Users

curl -X POST "https://api.hellojohn.dev/v1/admin/users/bulk-disable" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "usr_01HABCDEF123456",
      "usr_01HABCDEF789012"
    ],
    "revoke_sessions": true
  }'

Response:

{
  "disabled": 2,
  "sessions_revoked": 5
}

Force Password Reset

Send a password reset email to a user and optionally invalidate their current sessions:

curl -X POST "https://api.hellojohn.dev/v1/users/usr_01HABCDEF123456/password-reset" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{"revoke_sessions": true}'

Revoke All User Sessions

Sign a user out of all devices immediately:

curl -X DELETE "https://api.hellojohn.dev/v1/users/usr_01HABCDEF123456/sessions" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Remove MFA Factor (Admin)

Remove a user's MFA factor to allow recovery when they've lost access:

curl -X DELETE "https://api.hellojohn.dev/v1/users/usr_01HABCDEF123456/mfa/factors/fac_01HABCDEF555444" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

View User Audit Events

Fetch all audit events for a specific user:

curl "https://api.hellojohn.dev/v1/audit-logs?actor_id=usr_01HABCDEF123456&limit=50" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

TypeScript Admin Client Pattern

import HelloJohn from "@hellojohn/node";

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

// Search for a user by email
async function findUser(email: string) {
  const { data } = await hj.users.list({ email });
  return data[0] ?? null;
}

// Disable + revoke all sessions
async function suspendUser(userId: string, reason: string) {
  await hj.users.update(userId, { disabled: true });
  await hj.sessions.revokeAll(userId);

  await hj.auditLogs.create({
    action: "user.suspended",
    actor: "admin",
    resource_id: userId,
    metadata: { reason },
  });
}

// Generate impersonation session for support
async function impersonateUser(userId: string, reason: string) {
  const { access_token } = await hj.admin.impersonate({
    user_id: userId,
    reason,
    expires_in: "1h",
  });
  return access_token;
}

Best Practices

  • Log impersonation — Always require a reason and record who initiated it
  • Limit impersonation duration — Use the shortest TTL needed (1h is usually enough)
  • Require MFA for admins — Enforce MFA on any account with access to admin endpoints
  • Audit admin actions — Query audit logs regularly for anomalous admin activity
  • Use scoped keys — Give admin API keys only the scopes they need

Roles & Permissions

Configure role-based access control (RBAC) in HelloJohn — built-in roles, custom roles, permission scopes, and enforcing roles in your backend.

Organizations

What organizations are, how they work in HelloJohn, and how to build multi-tenant product experiences.

On this page

Admin User ManagementList All UsersQuery ParametersAdvanced User SearchSearch FiltersImpersonate a UserDisable a UserBulk Disable UsersForce Password ResetRevoke All User SessionsRemove MFA Factor (Admin)View User Audit EventsTypeScript Admin Client PatternBest PracticesRelated