Skip to main content

Setup

Pass an admin config when creating your theAuth instance. theauth.admin is null unless the admin key is passed, so use theauth.admin!. (or ?.) in your code.
Admin status is determined by the 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

Each user object includes id, email, name, banned, banReason, banExpiresAt, agentCount, and createdAt. limit defaults to 50. theauth.admin.getUser(userId) returns one user or null.

Banning users

Banning deletes all of the user’s sessions and marks every agent they own as revoked. Unbanning clears the ban fields but does not restore revoked agents or sessions.
theAuth records the ban (banned, banReason, banExpiresAt) but the sign-in modules do not check it, and nothing lifts a ban when banExpiresAt passes. Check theauth.admin.getUser(id) in your own sign-in flow and call unbanUser yourself when a temporary ban lapses.

Impersonation

Impersonation creates a real session token. Use it only for debugging and support. Impersonated sessions carry impersonating: true and the originating adminUserId in their session metadata.
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

This sets a 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

Deleting removes all sessions, marks owned agents as 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 the admin() 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.

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.
Last modified on October 18, 2026