commerce-canon/research/identity-provisioning/zitadel-organizations-projects.md

# ZITADEL Organizations and Projects

## Source Type

Product documentation and implementation reference for ZITADEL's multi-instance
organization, project, and grant model.

## Domain

Cloud-native IAM, multi-tenancy, B2B SaaS identity, and fine-grained
authorization grants.

## Why This Source Matters

ZITADEL organizations, projects, roles, grants, and multi-tenancy concepts.

ZITADEL is designed for multi-tenant SaaS from the ground up. Its org →
project → grant hierarchy provides a live product vocabulary for separating
customer organizations, application projects, and role grants.

## Key Concepts

- **Instance**: ZITADEL deployment; top-level operational boundary.
- **Organization**: primary tenant/customer entity; owns users, projects,
  policies, and branding.
- **Project**: application or service scope within an organization; owns roles,
  applications, and grants.
- **Application**: OIDC/SAML/API client registered under a project.
- **User**: human identity within an organization with authentication methods
  and profile.
- **Machine user / service user**: non-human identity for API access.
- **Grant**: assignment of project roles to a user or organization (including
  cross-org grants for B2B).
- **Role**: project-scoped permission label granted via grants.
- **Organization domain**: verified domain for org discovery and policy.
- **User grant vs. org grant**: direct user-to-project role vs. org-wide
  project access.
- **Actions / Flows**: customizable authentication and provisioning pipelines.

## Relevant Terminology

| Term | Source meaning |
| --- | --- |
| Organization | Customer or business entity; primary multi-tenant partition. |
| Project | Application or product scope within an org. |
| Grant | Role assignment linking user or org to a project. |
| Role | Named capability within a project. |
| User | Human identity record within an organization. |
| Machine user | Service identity for programmatic access. |
| Application | Registered client (OIDC/SAML/API) under a project. |
| Instance | ZITADEL deployment boundary. |
| Org grant | Organization-level access to a project's roles. |
| Domain verification | Proof that an org controls an email domain. |

## Modeling Assumptions

- **Organization is the primary customer/tenant boundary** for users and
  admin delegation.
- **Project separates applications** within an org; roles are project-scoped.
- **Grants are the authorization assignment mechanism**, not group membership.
- **Users belong to exactly one organization** (per current product model);
  cross-org access is via grants to shared projects.
- **Machine users are first-class** identities distinct from human users.
- **B2B** is modeled by granting one organization's project roles to another
  organization's users or to the org itself.
- **Branding and login policy** are org-scoped configuration.

## Identity-Canon Implications

- ZITADEL **Organization** maps to **Organization** actor and/or **Tenant**
  Scope depending on deployment (often both: org as actor, org as tenant
  boundary).
- **Project** maps to **Application Scope** or child **Scope** under tenant.
- **User** maps to **Account** (human); **Machine user** maps to **Service
  Account**.
- **Grant** maps to **Role** assignment via **Delegation** or Membership-like
  relationship with authorization implication.
- **Role** maps to **Role** (authorization projection).
- **Application** maps to registered client within Application Scope.
- **Domain verification** maps to **Claim** or **Evidence Source** for org
  domain ownership.
- Product vocabulary strongly supports S04 (vendor/customer) and S05
  (delegated admin via grants).

## Terminology Conflicts

- **Organization vs. Tenant**: ZITADEL uses "organization" for what SaaS
  products often call "tenant."
- **Grant vs. Membership**: grants assign roles; no generic group concept at
  project level.
- **User vs. Account**: product says "user" but means org-local identity
  record with credentials.
- **Project vs. Application**: project is container; application is client;
  both compete with "tenant" in other products.
- **Role vs. Grant**: role is definition; grant is assignment; IAM products
  often collapse these.

## Candidate Canonical Mappings

| ZITADEL concept | Candidate canonical concept |
| --- | --- |
| Instance | Scope (deployment boundary) |
| Organization | Organization + Tenant Scope |
| Project | Application Scope |
| User | Account |
| Machine user | Service Account |
| Application | Registered client / Application Scope |
| Role | Role (authorization projection) |
| Grant | Role assignment relationship (Delegation-like) |
| Org grant | Membership or Delegation at org level |
| Domain verification | Claim + Evidence Source |
| User profile | Profile |

## Open Questions

- When ZITADEL Organization serves as both commercial actor and isolation
  boundary, should canon use one node with dual typing or separate Organization
  + Tenant linked by Ownership?
- How should cross-org project grants map: **Delegation**, **Trust**, or a
  vendor-specific **Grant Relationship**?
- Does single-org-per-user constraint affect canon modeling of multi-org
  persons (S02)?
- Should Machine user always map to Service Account, or sometimes to
  Artificial Agent?

## References

- ZITADEL documentation — https://zitadel.com/docs
- ZITADEL Organizations — https://zitadel.com/docs/guides/manage/console/organizations
- ZITADEL Projects and roles — https://zitadel.com/docs/guides/manage/console/projects