---
name: bijection-tenants
description: "Evaluate and integrate the Tenants component with Bijection."
---

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

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @djpanda/convex-tenants. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses convex-tenants. Follow the installation and configuration steps exactly.

# convex-tenants

## Instructions

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.

### Installation

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

Current npm version: `@djpanda/convex-tenants@0.5.0`

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

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by convex-tenants is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40djpanda%2Fconvex-tenants)
- [GitHub repository](https://github.com/dbjpanda/convex-tenants)
- [Live demo](https://github.com/dbjpanda/convex-tenants/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/djpanda/convex-tenants)
- [Convex documentation](https://docs.convex.dev)