Setup
Pass anadmin config when creating your theAuth instance. theauth.admin is null unless the admin key is passed, so use theauth.admin!. (or ?.) in your code.
adminUserIds list. There is no role column, keep these IDs in environment variables, not hardcoded. theauth.admin.isAdmin(userId) checks membership.
To expose HTTP endpoints, add the admin() plugin (from @glinr/theauth/auth) with the same options instead. The plugin endpoints require an authenticated user who is in adminUserIds (401 without a user, 403 for non-admins).
Listing users
id, email, name, banned, banReason, banExpiresAt, agentCount, and createdAt. limit defaults to 50. theauth.admin.getUser(userId) returns one user or null.
Banning users
revoked. Unbanning clears the ban fields but does not restore revoked agents or sessions.
Impersonation
impersonate throws if allowImpersonation is false, if no session manager is configured, or if the first argument is not in adminUserIds. The returned session.expiresAt and the impersonationExpiresAt metadata reflect impersonationTtlSeconds, but the session record itself expires after auth.session.maxAge (7 days by default). Call stopImpersonation when the support session ends.
Force password reset
forcePasswordReset flag on the user. The sign-in gate checks the flag on every path that issues a session. A flagged user gets a 403 PASSWORD_RESET_REQUIRED response with a signed challenge, and finishes with POST /auth/sign-in/password-change. See the gate page for the paths that are not covered yet.
Deleting users
revoked so their records remain, then removes the user record.
Audit callback
onAdminAction receives { adminUserId, action, targetUserId, details?, timestamp } for ban_user, unban_user, delete_user, force_password_reset, and impersonate. Only impersonate records the real admin ID. The other actions are logged with adminUserId: 'system'. Errors thrown by the callback are swallowed.
Endpoints
With theadmin() plugin, all endpoints require an authenticated admin:
The plugin has no stop-impersonation endpoint, call
theauth.admin.stopImpersonation from your own code.
The module’s own theauth.admin.handleRequest is a different, unauthenticated surface (it serves the same paths but takes adminUserId in the body for impersonation and adds POST /auth/admin/stop-impersonation). Do not expose it to the internet without your own admin check.
Related
Organizations
Multi-tenant support with org-level roles and membership management.
API keys
Create scoped API keys for machine-to-machine callers.
Audit
Audit trail for agent activity. Admin actions are reported through
onAdminAction.SCIM
Automated user provisioning and deprovisioning via directory sync.