zitadel/apps/docs/content/guides/manage/console/projects-overview.mdx

---
title: Organize applications, services, and roles with projects
sidebar_label: Projects
sidebar_position: 4
---

import ProjectDescription from "../../../concepts/structure/_project_description.mdx";

## What is a project?

<ProjectDescription components={props.components} name="ProjectDescription" />

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`).
* **Applications:** Your web portal for administration, your iOS app, and your Android app would all be defined as **Applications** within this single Project.
* **Roles:** You would create **Roles** (e.g., `admin`, `cashier`, `viewer`) inside this Project.
* **Authorization:** All applications in this project share these roles, allowing you to create unified authorizations for your users across all platforms.

![POS Project](../../../../public/img/guides/console/posproject.png)

## 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](./applications-overview) for more details.

### Roles
A role consists of different attributes, but only the **Key** is relevant to the authorization and must be unique within the project.
* **Key:** The identifier used in code (e.g., `role.admin`).
* **Display Name:** A human-readable name for the UI.
* **Group:** Enables better handling in the ZITADEL Management Console (e.g., giving a user all roles of a specific group).

Read more about managing roles [here](./roles).

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

<Callout type="caution">
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.
</Callout>

![Default Project](../../../../public/img/guides/solution-scenarios/console-default-project.png)

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

<img
  alt="Empty Project"
  src="/docs/img/console_projects_empty.png"
  width="270px"
/>

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.

* **The Concept:** You enable another organization to use your Project.
* **Delegation:** The granted organization can manage the authorizations of *their own users* for your project. They can assign the roles you defined to their employees without your intervention.
* **Isolation:** You can select specifically which roles are available to the granted organization. This allows you to restrict features (e.g., "Premium" roles) per customer.

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.

<img
  alt="Granted project"
  src="/docs/img/guides/console/grantedprojectgrid.png"
  width="320px"
/>

### How to Grant a Project

1.  Navigate to the Project you want to share (e.g., `POS`).
2.  In the **Grants** section, click **New**.

<img src="/docs/img/guides/console/grantsmenu.png" alt="Grants" width="170px" />

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.

<img
  src="/docs/img/guides/console/projectbranding.png"
  alt="Project branding"
  width="400px"
/>

| 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 [primary domain scope](/apis/openidoauth/scopes#reserved-scopes) (e.g., `urn:zitadel:iam:org:domain:primary:{domainname}`).

### Role Settings
You can configure strict security checks regarding roles during authentication.

<img
  src="/docs/img/guides/console/rolesettings.png"
  width="700px"
  alt="Role settings"
/>

* **Assert Roles on Authentication:** Role information is sent from the Userinfo endpoint (and in tokens, depending on app settings).
* **Check authorization on Authentication:** Users are **only** allowed to login if they have at least one role assigned for this project. If they have no roles, access is denied immediately.
* **Check for Project on Authentication:** Checks if the user's organization actually has a grant for this project. If not, the user cannot be authenticated.

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

<img
  src="/docs/img/guides/console/tokenroles.png"
  width="700px"
  alt="Roles in token"
/>

You can learn more about Application and Token settings [here](./applications-overview).