docs: introduce versioned docs and migrate to fuma (#11166)

## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
2026-10-28 18:12:16 +00:00 · 2026-01-29 08:38:36 -08:00
parent 7b6395c348
commit d8ea041c56
2826 changed files with 78739 additions and 23571 deletions
@@ -0,0 +1,12 @@
+Managers are [human users or service users](/guides/manage/console/users-overview) who have permission to manage resources within ZITADEL.
+
+Manager permissions can be assigned to different levels in ZITADEL:
+
+- **IAM Managers**: This is the highest level. Users with IAM Administrator roles are able to manage the whole [Instance](/concepts/structure/instance).
+- **Org Managers**: Managers in the Organization Level are able to view or manage everything, according to their permissions, within the granted [Organization](/guides/manage/console/organizations-overview).
+- **Project Mangers**: In this level the user is able to manage a [project](/guides/manage/console/projects-overview).
+- **Project Grant Manager**: The project grant manager is for [granted projects](/concepts/structure/granted_projects) by another organization.
+
+The scope of the managers is restricted based on their level.
+Which means that a Manager, assigned to one organization, will have access only to the resources and configurations of that organization.
+Only the Managers on the instance level can view resources, such as users, across all organizations.
@@ -0,0 +1,17 @@
+ZITADEL is organized around the idea that:
+
+* Multiple organizations can be managed within one [instance](/concepts/structure/instance).
+* organizations can grant each other rights to self-manage certain aspects of the IAM (eg, roles for access management)
+* organizations are vessels for users and projects
+
+![](../../../public/img/concepts/objects/organization.png)
+
+Organizations in ZITADEL are therefore comparable to tenants of a system or organizational units of a directory based system.
+
+You can use projects within your organization to manage the security context of closely related components, such as roles, grants and authorizations for multiple clients. You can set up multiple projects within your organization.
+
+ZITADEL allows you to give other organizations permission to manage certain aspects of a project within your organization on their own. This means you could set up a project with roles that should exist within your service/software, but allow another organization to allocate the roles to users within their own organization. As a service provider, you will find this feature useful, as it allows you to establish a self-service culture for your business customers.
+
+![](../../../public/img/concepts/objects/organization_grants.png)
+
+Each organization has its own pool of usernames, which includes human and service users, for its domain (`{username}@{OrganizationDomain}.$CUSTOM_DOMAIN`). A username is unique within your organization. You can configure ZITADEL to use your own domain, and simplify user experience (`{loginname}@{yourdomain.tld}`).
@@ -0,0 +1,10 @@
+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.
+
+![](../../../public/img/concepts/objects/organization_grants.png)
+
+All applications within a project share the same roles, grants, and authorizations:
+
+- **Applications** is your software that initiates the authorization flow. This could be a web app and a mobile app that share the same roles.
+- **Roles** are a means of managing user access rights for a project.
+- **Authorizations** define which users have which roles. Authorizations are also called “user grants”.
+- **Granted Organizations** can manage selected roles for your project on their own.
@@ -0,0 +1,29 @@
+---
+title: Configure applications for your frontend and backend services and clients
+sidebar_label: Applications
+---
+
+import AppType from "../../guides/manage/console/_application-types.mdx";
+
+Applications are the entry point to your project.
+[Users](./users) either login into one of your clients and interact with them directly or use one of your APIs.
+All applications share the roles and authorizations of their [project](./projects).
+
+## Supported application types
+
+ZITADEL supports the following client types:
+
+<AppType components={props.components} />
+
+## Security considerations
+
+Ensure the configuration of application settings is limited to authorized users only.
+
+You can configure applications in the [management console](/guides/manage/console/organizations-overview).
+Read about our [managers](/concepts/structure/managers) and [granted projects](/concepts/structure/granted_projects)
+concepts.
+
+## References
+
+- [Configure Applications in the Management Console](../../guides/manage/console/applications-overview)
+- [ZITADEL API: Applications](/reference/api/application)
@@ -0,0 +1,14 @@
+---
+title: ZITADEL's Granted Projects
+sidebar_label: Granted Projects
+---
+
+# Granted Project
+
+![](../../../public/img/concepts/objects/organization_grants.png)
+
+With ZITADEL you can grant selected roles within your project to an organization. The receiving organization can then create authorizations for their users on their own (self-service).
+
+An example could be a service provider that offers a SaaS solution that has different permissions for employees working in Sales and Accounting. As soon as a new client purchases the service, the provider could grant the roles ‘sales’ and ‘accounting’ to that organization, allowing them to self-manage how they want to allocate the roles to their users.
+
+To learn more about how to setup Project grants, read this guide [here](../../guides/manage/console/projects-overview#granted-projects-b2b)
@@ -0,0 +1,13 @@
+---
+title: Structure
+---
+
+<Cards >
+  <Card  href="/concepts/structure/instance" title="Instance" />
+  <Card  href="/concepts/structure/organizations" title="Organizations" />
+  <Card  href="/concepts/structure/projects" title="Projects" />
+  <Card  href="/concepts/structure/applications" title="Applications" />
+  <Card  href="/concepts/structure/users" title="Users" />
+  <Card  href="/concepts/structure/managers" title="Managers" />
+  <Card  href="/concepts/structure/policies" title="Policies" />
+</Cards>
@@ -0,0 +1,32 @@
+---
+title: Instances
+sidebar_label: Instances
+---
+
+## Instance Structure
+
+An instance is the top node in ZITADEL's data hierarchy.
+Within an instance all the default [settings](/concepts/structure/policies),
+such as branding, login policy, password policy, etc. for the system can be configured.
+One instance normally runs on one domain and represents one issuer (e.g login.customer.com).
+
+One instance can contain multiple [organizations](/guides/manage/console/organizations-overview),
+which in turn can represent your own company (e.g. departments), your business customers or a consumer organization.
+
+Read more about how to configure your instance in our [instance guide](/guides/manage/console/default-settings).
+
+![](../../../public/img/concepts/objects/object_overview.png)
+
+This overview shows the general structure of ZITADEL.
+You will find more detailed explanations around the different concepts in the following sections.
+
+## Multiple Virtual Instances
+
+ZITADEL has the concept of virtual instances.
+When installing ZITADEL from scratch, one instance is always automatically created for you.
+Nevertheless, you can add more virtual instances via the [system API](/reference/api/system).
+This is useful if you have business customers, which in turn have their business customers with self service and Custom Domain demands.
+By providing a virtual ZITADEL instances, your customers have all the customization options available in ZITADEL.
+Scaling ZITADEL instances virtually enables you to easily distribute your limited compute resources to all your customers.
+
+![](../../../public/img/concepts/objects/instances.png)
@@ -0,0 +1,13 @@
+---
+title: Managers
+sidebar_label: Managers
+---
+
+import ManagerDescription from "./_manager_description.mdx";
+
+<ManagerDescription components={props.components}  name="ManagerDescription" />
+
+Notes:
+
+- Read our [guide on Managers](../../guides/manage/console/managers) to learn more about the role concept and how to use Administrator roles in ZITADEL.
+- [API reference](/apis/resources/mgmt/management-service-list-org-member-roles) for Managers on the organization level
@@ -0,0 +1,10 @@
+---
+title: ZITADEL Organizations
+sidebar_label: Organizations
+---
+
+import OrgDescription from './_org_description.mdx';
+
+<OrgDescription components={props.components} name="OrgDescription" />
+
+More about how to configure your organization read our [organization guide](../../guides/manage/console/organizations-overview).
@@ -0,0 +1,9 @@
+---
+title: ZITADEL Settings and Policies
+sidebar_label: Setting and Policies
+---
+
+Settings and policies are configurations of all the different parts of the instance or an organization. For all parts we have a suitable default in the instance.
+The default configuration can be overridden for each organization, some policies are currently only available on the instance level. Learn more about our different policies [here](/guides/manage/console/default-settings).
+
+API wise, settings are often called policies. You can read the proto and swagger definitions [here](../../apis/introduction).
@@ -0,0 +1,47 @@
+---
+title: Projects
+sidebar_label: Projects
+---
+
+import ProjectDescription from './\_project_description.mdx';
+
+<ProjectDescription components={props.components} name="ProjectDescription" />
+
+To learn how to set up a project read this management console guide [here](../../guides/manage/console/projects-overview.mdx).
+
+## Applications
+
+Applications define the different clients, that share the same roles.
+At the moment we support OIDC and almost every OAuth2 client. We'll be expanding this with SAML shortly.
+Go to [Applications](./applications) for more details.
+
+## Granted Organizations
+
+To enable another organization to use a project, the organization needs a grant to the project.
+Only the selected roles will be available to the granted organization.
+
+If you are unsure on how to structure your organizations and projects, we recommend reading the guide on [solution architecture](/concepts/architecture/solution).
+
+The granted organization will be able to manage the authorizations of their users for the granted project by themselves in their organization.
+
+More about granted projects: [Granted Projects](./granted_projects)
+
+## Roles
+
+A role consists of different attributes. Only the key is relevant to the authorization and must therefore be unique.
+The display name is only to provide a human-readable name if needed.
+And the group should enable a better handling in ZITADEL management console, like give a user all the roles of a specific group. (Not implemented yet)
+
+All applications in a project share the roles. Read more about roles [here](../../guides/manage/console/roles)
+
+## Default Project
+
+When creating a new ZITADEL instance you will find an automatically created project on the first created organization.
+This default project does represent the ZITADEL project and is used to secure the different apps shipped with ZITADEL.
+This includes the ZITADEL Management Console and APIs.
+
+We do not recommend changing any settings or using this project for anything else, as this could influence the behavior of ZITADEL.
+
+The default name of the project is "ZITADEL", this might differ on self-hosted instances, when you change the default name.
+
+![](../../../public/img/guides/solution-scenarios/console-default-project.png)
@@ -0,0 +1,81 @@
+---
+title: ZITADEL Users
+sidebar_label: Users
+---
+
+## Types of users
+
+ZITADEL supports authentication and authorization for different user types.
+We can mainly differentiate between Human Users and Machine Users.
+We typically call human users simply "Users" and machine users "Service Users".
+
+### Human users
+
+Human users typically logon with an interactive login.
+This means that an application redirects a user to a website ("login page") where the user can provide the credentials.
+ZITADEL handles the authentication and provides the application with a token that verifies the authentication process.
+
+Read more on how to [login users with ZITADEL](/guides/integrate/login/login-users).
+
+### Service users
+
+Service users are for machine-to-machine communication and you would use those typically to access secure backend services.
+For example in ZITADEL you would require an authenticated Service User to access the Management API.
+The main difference between human and machine users is the type of credentials that can be used for authentication: Human users typically logon via an login prompt, but Machine users require a non-interactive logon process.
+
+Learn how to [use service users](/guides/integrate/service-users/authenticate-service-users) with ZITADEL.
+
+### Managers
+
+Any user, human or service user, can be given a [Manager](/concepts/structure/managers) role.
+A user with an administrator role is not only an end-user of ZITADEL but can also manage certain aspects of ZITADEL itself.
+
+### Federated users
+
+Federated users are identities that are managed by a third-party identity provider.
+Users can login via an external identity provider, using [identity brokering](../features/identity-brokering) ("Single-sign-on").
+Federated user [accounts are linked](../features/account-linking) to internal users to be able to assign roles and keep an audit trail.
+
+### External users
+
+In a multi-tenancy architecture, you might use [organizations](./organizations) to separate user groups.
+By using [external user grants](../features/external-user-grant) an organization is able to invite users from another organization.
+These invited users are called external users.
+
+## Considerations
+
+### Uniqueness of users
+
+Users can only exist within one [organization](/guides/manage/console/organizations-overview).
+It is currently not possible to move users between organizations.
+
+User accounts are uniquely identified by their `id` or `loginname` in combination of the `organization domain` (eg, `[email protected]`).
+You can use the same email address for different user accounts.
+
+### How to structure user pools
+
+Consider this general recommendation as a starting point:
+
+- Create one organization ("default organization") for your own company
+- Configure projects and applications in the default organization
+- Structure users in organizations based on common domains that are self-managed (eg, company)
+- Grant your projects to the organizations, allow Managers to give granted roles to their users
+
+You might want to adjust this general setup based on your [scenario](/guides/solution-scenarios).
+
+One important consideration in the setup is that you can only have a domain once for an organization. If you have multiple teams working with the same email address, you might need to add them to one single organization that has the domain verified for the teams' domain.
+
+For a CIAM / B2C setup, you might want to store all users in one organization and allow that organization to use a specific set of social logins.
+In a multitenancy / B2B scenario, you might have thousands of smaller teams.
+
+#### Hierarchy
+
+There is no concept of hierarchies and inheritance based on users or organizations.
+This is why we recommend to structure users along the smallest unit of groups.
+You can use organization metadata or your own business logic to describe a hierarchy of organizations or user groups.
+
+## References
+
+- [Manage users in the Management Console](../../guides/manage/console/users-overview)
+- [ZITADEL APIs: Users](/reference/api/user)
+- [User onboarding and registration](/guides/integrate/onboarding)