Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kavachos.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

MethodPathDescription
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.
Last modified on April 29, 2026