Setup Pass adminUserIds when creating your KavachOS instance:
import { createKavach } from 'kavachos' ; const kavach = await createKavach ({ database: { provider: 'sqlite' , url: 'kavach.db' }, admin: { adminUserIds: [ process . env . ADMIN_USER_ID ], allowImpersonation: true , }, });
Admin status is determined by the adminUserIds list. There is no role column, keep these IDs in environment variables, not hardcoded.
Listing users const { users , total } = await kavach . admin . listUsers ({ limit: 50 , offset: 0 , search: 'alice' , // optional email filter });
Each user object includes id, email, name, banned, banReason, banExpiresAt, agentCount, and createdAt.
Banning users // Permanent ban await kavach . admin . banUser ( 'user_xyz' , 'Violating terms of service' ); // Temporary ban await kavach . admin . banUser ( 'user_xyz' , 'Spam' , new Date ( '2025-06-01' )); // Lift the ban await kavach . admin . unbanUser ( 'user_xyz' );
Banning immediately revokes all active sessions for that user.
Impersonation Impersonation creates a real session token. Use it only for debugging and support. All impersonated sessions are tagged with impersonating: true and the originating adminUserId.
const { session } = await kavach . admin . impersonate ( 'admin_abc' , 'user_xyz' ); // session.token: use this as a regular session token // session.expiresAt // Stop impersonating await kavach . admin . stopImpersonation ( session . token );
Force password reset await kavach . admin . forcePasswordReset ( 'user_xyz' );
This sets a flag on the user. Your app should check user.forcePasswordReset after login and redirect to a reset flow.
Deleting users await kavach . admin . deleteUser ( 'user_xyz' );
Deleting revokes all sessions and marks owned agents as revoked to preserve the audit trail, then removes the user record.
Endpoints Method Path Description GET /auth/admin/usersList users (limit, offset, search) GET /auth/admin/users/:idGet user POST /auth/admin/users/:id/banBan user POST /auth/admin/users/:id/unbanUnban user DELETE /auth/admin/users/:idDelete user POST /auth/admin/impersonate/:userIdImpersonate user POST /auth/admin/stop-impersonationEnd impersonation session
Organizations Multi-tenant support with org-level roles and membership management.
API keys Create scoped API keys for machine-to-machine callers.
Audit Full activity trail for impersonation and admin actions.
SCIM Automated user provisioning and deprovisioning via directory sync.
