ZITADEL Projects: Manage Apps, Services & Roles | ZITADEL Docs

ZITADEL Projects: Manage Apps, Services & Roles

What is a project?

The idea of projects is to have a vessel for all components who are closely related to each other. Multiple projects can exist within an organization.

All applications within a project share the same roles, grants, and role assignments:

A Project is the vessel that holds your Applications and Roles. It defines the security context for a specific software solution.

Example Scenario

Imagine you are building a Point of Sales (POS) platform. In ZITADEL, you would create one Project (e.g., named POS).

Core Components

Applications

Applications define the different clients (web apps, native mobile apps, server-side APIs) that share the same roles and security context. At the moment, we support OIDC and almost every OAuth2 client. We'll be expanding this with SAML shortly. Go to Applications for more details.

Roles

A role consists of different attributes, but only the Key is relevant to the role assignment and must be unique within the project.

Read more about managing roles here.

The Default Project

When creating a new ZITADEL instance, you will find an automatically created project in the first organization. This Default Project (named "ZITADEL") protects the ZITADEL Management Console and APIs.

We do not recommend changing any settings in the Default Project or using it for your own applications, as this could influence the behavior of ZITADEL itself.

Create a Project

To create a project:

  1. Navigate to your Organization in the Console.

  2. Go to Projects (or visit https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/projects).

  3. Click the Create New Project button.

  4. Enter your project name and continue.

Granted Projects (B2B)

A powerful feature of ZITADEL is the ability to Grant a project to other organizations. This is essential for B2B scenarios where you sell your software to business partners.

Using the POS example above: You could grant the POS project to a partner organization. That partner can then log in with their own domain, use their own branding, and manage their own cashier users, all while using your underlying application structure.

How to Grant a Project

  1. Navigate to the Project you want to share (e.g., POS).

  2. In the Project Grants section, click New.

  3. Enter the Domain of the partner organization you want to grant access to.

    • Tip: If you don't know the domain, navigate to the Organization detail page to find it.
  4. Search and select the organization.

  5. Select the Roles you want to grant to this organization and click Save.

Project Settings

You can customize the behavior of your project, particularly regarding how login screens look and how tokens are issued.

Branding

If you have different designs for your organizations (Private Labeling), you can define the login behavior on the project detail page.

Setting Description
Unspecified If nothing is specified, the system default settings will trigger.
Enforce project's policy This forces the branding of the organization that owns the project throughout the entire login process. Useful if you want your users to always see your brand, even if they belong to a partner org.
Allow login user policy The login starts with the project's branding. However, as soon as the user is identified (e.g., by entering their email), the branding switches to match the user's organization.

In a B2B use case, you would typically use Allow login user policy. If you want to skip the detection step, you can preselect an organization using the Organization Domain scope (e.g., urn:zitadel:iam:org:domain:primary:{domainname}).

Role Settings

You can configure strict security checks regarding roles during authentication.

Roles in Tokens

If you want roles to appear directly inside your Access or ID Tokens (to avoid calling the Userinfo endpoint), you must enable this per application.

  1. Navigate to your Application.
  2. Open Token Settings.
  3. Check Assert Roles on Authentication.

You can learn more about Application and Token settings here.