Zitadel multi-tenant B2B setup with organizations

A project grant lets users in one Zitadel organization use an application and its roles that are defined in a different organization. The project itself stays where it was created. The grant is a separate record that points at that project, names the organization receiving access, and selects which of the project's roles those users may receive. For multi-tenant B2B design, this is the mechanism that lets a shared application serve many customers without copying the application into each customer's organization.

Consider an illustrative example. A platform vendor runs an invoicing application as a project in its own organization. A partner organization wants its staff to use that application. The vendor creates a grant from its project to the partner's organization and selects the roles the partner may assign, such as an invoice viewer and an invoice approver. Partner administrators then assign those granted roles to their own users. The vendor keeps control of the application definition, the role catalogue and the client configuration, while the partner controls who on their side holds each role.

Confirm who is allowed to create grants before you design around them. In Zitadel, grant creation is governed by the permissions held by the instance and organization administrators involved, and those permissions differ by how the organization and project are set up. Check which roles can create, edit and revoke grants, whether a project owner in one organization can grant to another without involvement from an instance administrator, and whether the receiving organization can refuse or limit what it receives. Write these answers into your access policy so that a delegated administrator in a customer organization cannot widen access on their own.

Map the granted roles to the receiving organization's users carefully. A granted role is only a permission set on the project. Users in the receiving organization do not become members of the granting organization, and their identities, credentials and authentication policies remain in their own organization. Test a user from each receiving organization end to end, confirming that the token they receive contains the expected roles and that roles outside the grant are absent. Also decide what happens when a role is renamed or removed in the source project, because existing grants and user assignments may need updating.

Plan for departure. When a customer leaves, revoking the grant should remove that organization's access to the shared project, but it does not by itself delete the users, role assignments or audit records created in the customer's organization. Decide whether those users are disabled, moved or deleted, and whether tokens already issued remain valid until they expire. Confirm the revocation behavior, the token lifetime and the data retention rules against the Zitadel organizations documentation and your target release, and rehearse the offboarding procedure in a non-production instance before relying on it.

Before any customer organization signs in, run a documented isolation test that tries to break the boundaries you designed. The goal is to prove that an account in one organization cannot see or change anything that belongs to another, and that a fault in one customer's identity setup stays contained. Treat this as a release gate for the Zitadel multi-tenant design, not a one-time demo. Keep the test scripts and results in the same repository as your instance and organization design so they can be rerun.

Start with cross-organization reads. Create at least two test organizations inside the same instance, each with a user, a project and an application. From an account in organization A, attempt to read users, projects and applications belonging to organization B, both in the Console and through the management API using a token issued to the A account. Repeat the attempts with a user who holds an organization-level administrator role in A. Every attempt should return a denial or an empty result. Also check that the instance-level administrator behavior matches what your operating model says it should be, since that account sits above the organizations.

Next, test grants. A project grant should make a project visible to exactly the organization it was granted to, and nobody else. Grant a project from organization A to organization B, confirm that a B user can see the granted project and its roles, then confirm that a third organization cannot. Then revoke the grant and verify that B users lose access to the project and its applications on their next token request. Check existing sessions and refresh tokens as well, because a revoked grant that still works through a cached token is a finding. Record the exact time of revocation and the time access stopped.

Test delegated administration separately. Create a user in organization A with the role you intend to delegate to customer administrators, then try to change organization B: rename it, add users, edit its identity provider, alter its login policies, or create projects in it. Each of these should fail. Repeat the same checks after you have changed role assignments, because a role granted at the wrong level is the most common way tenant boundaries erode. Confirm the delegated role appears only in the scope you intended.

Finally, test failure and change. Break the identity provider for one organization, for example by pointing its configured upstream provider at an invalid endpoint or disabling its client, then confirm that users in every other organization can still sign in. After any configuration change, rerun the full set of cross-organization reads, grant and revoke checks, and delegated admin attempts, not only the tests for the area you changed. A wrong design usually shows up as a successful read or write across the boundary, a revoked grant that keeps working, or one organization's outage blocking logins elsewhere. Save every result, including timestamps, test accounts, commands and screenshots, as test evidence for your compliance file, and ask your auditor which format they expect before you start.

The go-live of a multi-tenant Zitadel setup is the start of the operating work, not the end of it. Within the first weeks, the platform team should hold a current register that answers three questions at any time: which instances exist, which organizations sit inside each instance, and which projects and grants connect them. Each entry needs a named owner, a purpose and the date it was last reviewed. Record the instance and organization identifiers, the project names, the roles defined on each project, and every project grant that lets one organization use another organization's project. Without this register, a later question such as "who can still reach this customer's applications?" becomes an investigation rather than a lookup.

Delegated administration needs its own review cadence because it is the control most likely to drift. Customer organizations are often given administrative roles inside their own organization so they can manage their users and applications. Review those accounts and their role assignments on a fixed schedule, and remove access that no longer matches a contract or a named contact. Review project grants with the same rigor. A grant that was useful during onboarding can outlive the reason for it. Confirm the review interval with your security and compliance owners, and keep the output of each review in the register so the decision and its date are traceable. The Zitadel audit and event views are the starting point for evidence, but confirm in your own version which events are retained and for how long.

Onboarding and offboarding of customer organizations should be a written procedure with checks at each step, not an informal set of console actions. Onboarding normally covers creating the organization, assigning its administrators, attaching its identity provider where one applies, creating project grants, and recording the change in the register. Offboarding must do the reverse in a defined order: disable sign-in for the organization's users, revoke grants and delegated administrator roles, remove or archive applications, and then confirm that the organization's identity provider and client registrations no longer accept logins. Decide in advance what happens to the organization's user data, and who approves deletion. Test the procedure in a non-production instance before the first real offboarding.

Upgrades across the v4 line must be treated as changes that can affect tenant isolation, not only as package updates. Zitadel v4.19.5 was published on 15 October 2026 and can serve as a reference point, but check the GitHub releases page for the release you actually plan to run, and read its notes before every change. For each upgrade, rerun a fixed set of isolation tests: a user in one organization cannot read or authenticate into another, a grant does not expose more roles than intended, and each customer's identity provider still routes only its own users. Record the test results alongside the change ticket. Support, upgrade paths and database migration testing are covered on the upgrades page, so this section only sets the controls that trigger those activities.