Convex Tenants

Convex Tenants

Multi-tenant organization and team management for Convex with flexible authorization via @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;

2. 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.

3. 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;
    },
  });

4. 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

Documentation (read from package)

Base path: node_modules/@djpanda/convex-tenants/docs/. Select the doc that matches the user's keywords or task — load only what's needed:

Installation

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

For React UI: npm install clsx tailwind-merge (optional peer deps).