# Tenants

Application organizations and teams

- Package: @bijectionhq/tenants
- Category: Authentication
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/tenants/tree/509ec2fd2b19ec08a9ad19c255b9f6b5d92ee22f
- Upstream: https://github.com/dbjpanda/convex-tenants/tree/e2a3f2455912765eb5315f6d2493826433ae172a
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/tenants

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/tenants.git
cd tenants
git checkout 509ec2fd2b19ec08a9ad19c255b9f6b5d92ee22f
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @djpanda/convex-tenants; check the Bijection adaptation separately.

A multi-tenant component that adds organization, team, and member management to Convex applications with built-in authorization via @djpanda/convex-authz. Provides complete CRUD operations for organizations with unique slugs and status management, role-based member management, team creation and membership, and a flexible invitation system. Includes React hooks, UI components, and an organization store for client-side state management.

### Use cases

• **Building SaaS applications** where users need to create and manage organizations with different permission levels for team members
• **Enterprise applications** requiring team-based access control with custom roles and hierarchical permissions within organizations
• **Collaborative platforms** where users can be members of multiple organizations and switch between different organizational contexts
• **B2B applications** needing invitation workflows to onboard new team members with specific roles and team assignments
• **Multi-tenant apps** requiring organization suspension and archival capabilities for administrative control

### How it works

The component integrates with your Convex app by registering `tenants` and `authz` in `convex.config.ts`, then defining permissions and roles in `authz.ts` using the provided `TENANTS_PERMISSIONS` and `TENANTS_ROLES` constants. You create a `convex/tenants.ts` file that calls `makeTenantsAPI()` with your auth configuration, which generates a complete set of queries and mutations for organization, member, team, and invitation management.

Authorization is handled through `@djpanda/convex-authz` with a customizable permission map that defines which permissions are required for each operation. Organizations can have statuses (active, suspended, archived) that automatically block mutations when not active. The invitation system supports flexible identifiers beyond email, with customizable validation callbacks.

On the client side, React applications can use the `TenantsProvider` and included hooks like `useQuery(api.tenants.listOrganizations)` to interact with the backend. The component provides pre-built UI components including an organization switcher and management dialogs, plus an organization store that maintains active organization state with configurable storage keys.

### Upstream README

# @djpanda/convex-tenants

A multi-tenant organization and team management component for [Convex](https://convex.dev) with flexible, developer-defined authorization via [`@djpanda/convex-authz`](https://github.com/dbjpanda/convex-authz).

## Features

- **Organizations** — Create, update, delete; unique slugs; optional status (`active` / `suspended` / `archived`); transfer ownership; list filtered by status; mutations blocked when org is suspended/archived (reactivate via `updateOrganization` with `status: "active"`)
- **Members** — Add, remove, update roles; roles are flexible strings you define in authz; cursor-based [paginated list](docs/api-reference.md) for large member lists
- **Teams** — Create teams with optional slug and metadata; manage membership; [paginated lists](docs/api-reference.md) for teams and for team members
- **Invitations** — Flexible identifier-based invitations (email, phone, username, etc.); customizable validation callbacks for create and accept; optional message and team assignment; customizable expiration; [paginated list](docs/api-reference.md)
- **Authorization** — Define permissions and roles in `authz.ts` with `@djpanda/convex-authz`; customizable [permission map](docs/permission-map.md)
- **React** — Hooks, `TenantsProvider`, and pre-built UI (switcher, members, teams, invitations); [organization store](docs/organization-store.md) with configurable storage key

## Installation

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

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

## Quick Start

1. Register `tenants` and `authz` in `convex/convex.config.ts`.
2. Create `convex/authz.ts` with permissions and roles (use `TENANTS_PERMISSIONS` / `TENANTS_ROLES` from this package).
3. Create `convex/tenants.ts` with `makeTenantsAPI(components.tenants, { authz, auth, getUser, ... })` and export the returned functions.
4. Use the exported queries/mutations in your app (e.g. `useQuery(api.tenants.listOrganizations)`).

**Full walkthrough:** [Quick Start](docs/quick-start.md).

## Documentation

| Topic | Description |
|-------|-------------|
| [Quick Start](docs/quick-start.md) | Step-by-step setup and first API usage |
| [API Reference](docs/api-reference.md) | All `makeTenantsAPI` options and functions |
| [Permission Map](docs/permission-map.md) | Default permissions per operation and overrides |
| [Flexible Roles](docs/flexible-roles.md) | Custom roles and structural owner rules |
| [Invitation System](docs/invitation-system.md) | Flexible identifier validation and examples |
| [Migration Guide](MIGRATION_GUIDE.md) | Breaking changes and upgrade instructions |
| [React Components](docs/react-components.md) | TenantsProvider, OrganizationSwitcher, sections, dialogs |
| [Organization Store](docs/organization-store.md) | Active-org state and configurable storage key |

## Exported constants

| Export | Description |
|--------|-------------|
| `TENANTS_PERMISSIONS` | Default permissions; use with `definePermissions()` from `@djpanda/convex-authz`. |
| `TENANTS_ROLES` | Default roles (`owner`, `admin`, `member`); use with `defineRoles()`. |
| `DEFAULT_TENANTS_PERMISSION_MAP` | Operation → permission mapping. |
| `TENANTS_REQUIRED_PERMISSIONS` | Flat list of permission strings used by default. |

## License

MIT