Convex Tenants

@djpanda/convex-authz

Quick Start

1. Register components in

   convex/convex.config.ts

   :

import { defineApp } from "convex/server";
import tenants from "@djpanda/convex-tenants/convex.config";
import authz from "@djpanda/convex-authz/convex.config";

const app = defineApp();
app.use(tenants);
app.use(authz);

export default app;

1. Define authz in

   convex/authz.ts

   — use

   TENANTS_PERMISSIONS

   and

   TENANTS_ROLES

   from the package. See

   node_modules/@djpanda/convex-tenants/docs/quick-start.md

   .
2. Create tenants API in

   convex/tenants.ts

   :

import { makeTenantsAPI } from "@djpanda/convex-tenants";
import { components } from "./_generated/api";
import { authz } from "./authz";

export const { listOrganizations, createOrganization, inviteMember, ... } =
  makeTenantsAPI(components.tenants, {
    authz,
    creatorRole: "owner",
    auth: async (ctx) => (await getAuthUserId(ctx)) ?? null,
    getUser: async (ctx, userId) => {
      const user = await ctx.db.get(userId);
      return user ? { name: user.name, email: user.email } : null;
    },
  });

1. Use in React —

   useQuery(api.tenants.listOrganizations)

   , or use pre-built components with

   TenantsProvider

   . See

   node_modules/@djpanda/convex-tenants/docs/react-components.md

   .

Key Concepts

• authz is a sibling component — Register

  authz

  alongside

  tenants

  , not as a child. Other parts of your app can use authz outside tenants.
• Roles are plain strings — Define them in authz.ts. Default roles:

  owner

  ,

  admin

  ,

  member

  . See

  node_modules/@djpanda/convex-tenants/docs/flexible-roles.md

  .
• Structural owner — Each org has an

  ownerId

  . Use

  transferOwnership

  before owner leaves. All permission checks go through authz.
• Organization status —

  suspended

  or

  archived

  blocks mutations; only

  updateOrganization

  with

  status: "active"

  can reactivate.

Exports

TENANTS_PERMISSIONS

definePermissions()

TENANTS_ROLES

defineRoles()

DEFAULT_TENANTS_PERMISSION_MAP

TENANTS_REQUIRED_PERMISSIONS

Documentation (read from package)

node_modules/@djpanda/convex-tenants/docs/

docs/quick-start.md

docs/api-reference.md

docs/permission-map.md

docs/flexible-roles.md

docs/invitation-system.md

docs/react-components.md

docs/organization-store.md

Installation

npm install @djpanda/convex-tenants @djpanda/convex-authz

npm install clsx tailwind-merge