Name: KavachOS
Author: KavachOS

Setup

Add the organization plugin to your KavachOS instance:

import { createKavach } from 'kavachos';
import { organization } from 'kavachos/auth'; 

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
  plugins: [
    organization({ 
      maxMembers: 100, 
      maxOrgsPerUser: 5, 
      allowCustomRoles: true, 
    }), 
  ],
});

Creating organizations

const org = await kavach.org.create({
  name: 'Acme Corp',
  slug: 'acme-corp',   // lowercase letters, numbers, hyphens only
  ownerId: 'user_abc',
  metadata: { plan: 'pro' },
});
// org.id = 'org_...'

The creator is automatically added as a member with the owner role.

Inviting members

const invitation = await kavach.org.invite({
  orgId: org.id,
  email: 'alice@acme.com',
  role: 'admin',
  invitedBy: 'user_abc',
});
// invitation.id, invitation.expiresAt (7 days)

Accept on the invited user's side:

const member = await kavach.org.acceptInvitation(invitation.id, 'user_xyz');

Managing members

// List all members
const members = await kavach.org.getMembers(org.id);

// Change a member's role
await kavach.org.updateMemberRole(org.id, 'user_xyz', 'member');

// Remove a member
await kavach.org.removeMember(org.id, 'user_xyz');

Roles and permissions

Four built-in roles ship by default:

Role	Permissions
`owner`	All permissions including `org:manage`, `org:delete`, `roles:manage`
`admin`	`members:invite`, `members:remove`, `agents:create`, `agents:revoke`, `agents:manage`
`member`	`agents:create`, `agents:manage`
`viewer`	None

Check permissions at runtime:

const allowed = await kavach.org.hasPermission(org.id, userId, 'agents:create');

Custom roles

await kavach.org.createRole(org.id, {
  name: 'billing',
  permissions: ['invoices:read', 'invoices:pay'],
});

Set allowCustomRoles: false in the plugin config to restrict orgs to the built-in roles only.

Endpoints

Method	Path	Description
POST	`/auth/org`	Create organization
GET	`/auth/org/user/:userId`	List orgs for user
GET	`/auth/org/:orgId`	Get organization
PATCH	`/auth/org/:orgId`	Update organization
DELETE	`/auth/org/:orgId`	Delete organization
GET	`/auth/org/:orgId/members`	List members
POST	`/auth/org/:orgId/members`	Add member
PATCH	`/auth/org/:orgId/members/:userId`	Update member role
DELETE	`/auth/org/:orgId/members/:userId`	Remove member
POST	`/auth/org/:orgId/invite`	Send invitation
GET	`/auth/org/:orgId/invitations`	List invitations
POST	`/auth/org/invite/:invitationId/accept`	Accept invitation
DELETE	`/auth/org/invite/:invitationId`	Revoke invitation
GET	`/auth/org/:orgId/roles`	List roles
POST	`/auth/org/:orgId/roles`	Create role
GET	`/auth/org/:orgId/permissions/:userId/:permission`	Check permission

Organizations