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]>

apps/docs/content/concepts/architecture/secrets.mdx

@@ -0,0 +1,137 @@
+---
+title: How ZITADEL Processes and Stores Secrets
+sidebar_label: Secrets
+---
+
+In this chapter you can find information of how ZITADEL processes and stores secrets and credentials in a secure fashion.
+
+<Callout>
+We use the terms secret and credentials interchangeable to keep this guide lean.
+</Callout>
+
+## Secrets Principles
+
+ZITADEL uses the following principles when handling Secrets across their lifecycle:
+
+- Automate rotation
+- Limit lifetime
+- Show only once
+- Prefer public / private key concepts (FIDO2, U2F, JWT Profile, ...)
+- Irreversible hash secrets / passwords
+- Encrypt secrets storage
+- When sent across unsecure channels (eMail, SMS, ...)
+  - Forced changed through receiver
+  - Verify that the secret can only be used once
+
+## Secrets Storage
+
+By default ZITADEL stores secrets from its users, clients as well as its generated secrets like signing keys in the database.
+To protect the secrets against extraction from database as well as database dumps they are encrypted with AES256.
+
+<Callout>
+The key used to encrypt and decrypt the secrets in the ZITADEL database is called `masterkey` and needs to be exactly 32 bytes long.
+The only secrets stored outside of the Secrets Storage are the masterkey, the TLS Keys, the initial Admin User (including the password)
+</Callout>
+
+## Secrets stored in the Secrets Storage
+
+### Public Keys
+
+ZITADEL does handle many different public keys. These include:
+
+- FIDO2
+- U2F
+- JWT Profile
+- Signing Keys
+
+<Callout>
+Due to the inherent nature of a public key being public we safeguard them against malicious key changes with our unique [eventstore concept](../eventstore/overview).
+</Callout>
+
+### Hashed Secrets
+
+ZITADEL does handle many different passwords and secrets. These include:
+
+- User Authentication
+  - Password
+- Client / Machine Authentication
+  - Client Secrets
+
+<Callout>
+ZITADEL hashes all Passwords and Client Secrets in an non reversible way to further reduce the risk of a Secrets Storage breach.
+</Callout>
+
+Passwords and secrets are always hashed with a random salt and stored as an encoded string that contains the Algorithm, its Parameters, Salt and Hash.
+The storage encoding used by ZITADEL is Modular Crypt Format and a full reference can be found in our [Passwap library](https://github.com/zitadel/passwap#encoding).
+
+The following hash algorithms are supported:
+
+- argon2i / id[^1]
+- bcrypt (Default)
+- md5: implementation of md5Crypt with salt and password shuffling [^2]
+- md5plain: md5 digest of a password without salt [^2]
+- md5salted: md5 digest of a salted password [^2]
+- phpass: md5 digest with PHPass algorithm (used in WordPress) [^2]
+- drupal7: Custom hashing format used in Drupal 7 [^2]
+- sha2: implementation of crypt(3) SHA-256 & SHA-512
+- scrypt
+- pbkdf2
+
+[^1]: argon2 algorithms are currently disabled on ZITADEL Cloud due to its steep memory requirements.
+[^2]: md5 and drupal7 are insecure and can only be used to import and verify users, not hash new passwords.
+
+<Callout>
+ZITADEL updates stored hashes when the configured algorithm or its parameters are updated,
+the first time verification succeeds.
+This allows to increase cost along with growing computing power.
+ZITADEL allows to import user passwords from systems that use any of the above hashing algorithms.
+
+Note however that by default, only `bcrypt` is enabled.
+Further `Verifiers` must be enabled in the [configuration](/self-hosting/manage/configure) by the system administrator.
+</Callout>
+
+### Encrypted Secrets
+
+Some secrets cannot be hashed because they need to be used in their raw form. These include:
+
+- Federation
+  - Client Secrets of Identity Providers (IdPs)
+- Multi-factor Authentication
+  - TOTP Seed Values
+- Validation Secrets
+  - Verifying contact information like eMail, Phonenumbers
+  - Verifying proof of ownership over domain names (DNS)
+  - Resting accounts of users (password, MFA reset, ...)
+- Private Keys
+  - Token Signing (JWT, ...)
+  - Token Encryption (Opaque Bearer Tokens)
+  - Useragent Cookies (Session Cookies) Encryption
+  - CSRF Cookie Encryption
+- Mail Provider
+  - SMTP Passwords
+- SMS Provider
+  - Twilio API Keys
+
+<Callout>
+By default ZITADEL uses `RSA256` for signing purposes and `AES256` for encryption
+</Callout>
+
+## Secrets stored outside the Secrets Storage
+
+### Masterkey
+
+Since the Masterkey is used as means of protecting the Secrets Storage it cannot be stored in the storage.
+You find [here the many ways how ZITADEL can consume the Masterkey](/self-hosting/manage/configure).
+
+### TLS Material
+
+ZITADEL does support end to end TLS as such it can consume TLS Key Material.
+Please check our [TLS Modes documentation](/self-hosting/manage/tls_modes) for more details.
+
+### Admin User
+
+The initial Admin User of ZITADEL can be configured through [ZITADELs config options](/self-hosting/manage/configure).
+
+<Callout>
+To prevent elevated breaches ZITADEL forces the Admin Users password to be changed during the first login.
+</Callout>

apps/docs/content/concepts/architecture/software.mdx

@@ -0,0 +1,151 @@
+---
+title: Zitadel's Software Architecture
+sidebar_label: Software Architecture
+---
+
+Zitadel is built with two essential patterns. Event Sourcing (ES) and Command and Query Responsibility Segregation (CQRS).
+Due to the nature of Event Sourcing Zitadel provides the unique capability to generate a strong audit trail of ALL the things that happen to its resources, without compromising on storage cost or audit trail length.
+
+The combination of ES and CQRS makes Zitadel eventual consistent which, from our perspective, is a great benefit in many ways.
+It allows us to build a Source of Records (SOR) which is the one single point of truth for all computed states.
+The SOR needs to be transaction safe to make sure all operations are in order.
+You can read more about this in our [ES documentation](../eventstore/overview).
+
+Each Zitadel binary contains all components necessary to serve traffic
+From serving the API, rendering GUI's, background processing of events and task.
+This All in One (AiO) approach makes operating Zitadel simple.
+
+## The Architecture
+
+Zitadels software architecture is built around multiple components at different levels.
+This chapter should give you an idea of the components as well as the different layers.
+
+![](../../../public/img/zitadel_software_architecture.png)
+
+### Service Layer
+
+The service layer includes all components who are potentially exposed to consumers of Zitadel.
+
+#### HTTP Server
+
+The http server is responsible for the following functions:
+
+- serving the management GUI called Zitadel Management Console
+- serving the static assets
+- rendering server side html (login, password-reset, verification, ...)
+
+#### API Server
+
+The API layer consist of the multiple APIs provided by Zitadel. Each serves a dedicated purpose.
+All APIs of Zitadel are always available as gRCP, gRPC-web and REST service.
+The only exception is the [OpenID Connect & OAuth](/apis/openidoauth/endpoints) and [Asset API](/apis/introduction#assets) due their unique nature.
+
+- [OpenID Connect & OAuth](/apis/openidoauth/endpoints) - allows to request authentication and authorization of Zitadel
+- [SAML](/apis/saml/endpoints) - allows to request authentication and authorization of Zitadel through the SAML standard
+- [Authentication API](/apis/introduction#authentication) - allow a user to do operation in its own context
+- [Management API](/apis/introduction#management) - allows an admin or machine to manage the Zitadel resources on an organization level
+- [Administration API](/apis/introduction#administration) - allows an admin or machine to manage the Zitadel resources on an instance level
+- [System API](/apis/introduction#system) - allows to create and change new Zitadel instances
+- [Asset API](/apis/introduction#assets) - is used to upload and download static assets
+
+### Core Layer
+
+#### Commands
+
+The Command Side has some unique requirements, these include:
+
+- Transaction safety is a MUST
+- Availability MUST be high
+
+> When we classify this with the CAP theorem we would choose Consistent and Available but leave Partition Tolerance aside.
+
+##### Command Handler
+
+The command handler receives all operations who alter a resource managed by Zitadel.
+For example if a user changes his name. The API Layer will pass the instruction received through the API call to the command handler for further processing.
+The command handler is then responsible of creating the necessary commands.
+After creating the commands the command hand them down to the command validation.
+
+##### Command Validation
+
+With the received commands the command validation will execute the business logic to verify if a certain action can take place.
+For example if the user really can change his name is verified in the command validation.
+If this succeeds the command validation will create the events that reflect the changes.
+These events now are being handed down to the storage layer for storage.
+
+#### Events
+
+Zitadel handles events in two ways.
+Events that should be processed in near real time are processed by a in memory pub sub system.
+Some events can be handled asynchronously using the spooler.
+
+##### Pub Sub
+
+The pub sub system job is it to keep a query view up-to-date by feeding a constant stream of events to the projections.
+Our pub sub system built into Zitadel works by placing events into an in memory queue for its subscribers.
+There is no need for specific guarantees from the pub sub system. Since the SOR is the ES everything can be retried without loss of data.
+In case of an error an event can be reapplied in two ways:
+
+- The next event might trigger the projection to apply the whole difference
+- The spooler takes care of background cleanups in a scheduled fashion
+
+> The decision to incorporate an internal pub sub system with no need for specific guarantees is a deliberate choice.
+> We believe that the toll of operating an additional external service like a MQ system negatively affects the ease of use of Zitadel as well as its availability guarantees.
+> One of the authors of Zitadel did his thesis to test this approach against established MQ systems.
+
+##### Spooler
+
+The spoolers job is it to keep a query view up-to-date or at least look that it does not have a too big lag behind the Event Store.
+Each query view has its own spooler which is responsible to look for the events who are relevant to generate the query view. It does this by triggering the relevant projection.
+Spoolers are especially necessary where someone can query datasets instead of single ids.
+
+> Each view can have exactly one spooler, but spoolers are dynamically leader elected, so even if a spooler crashes it will be replaced in a short amount of time.
+
+#### Projections
+
+Projections are responsible of normalizing data for the query side or for analytical purpose.
+They generally work by being invoked either through a scheduled spooler or the pub sub subscription.
+
+When they receive events they will create their normalized object and then store this into the query view and its storage layer.
+
+#### Queries
+
+The query side is responsible for answering read requests on data.
+It has some unique requirements, which include:
+
+- It needs to be easy to query
+- Short response times are a MUST (80%of queries below 100ms on the api server)
+- Availability MUST be high, even during high loads
+- The query view MUST be able to be persisted for most request
+
+> When we classify this with the CAP theorem we would choose **Available** and **Performance** but leave **Consistent** aside
+
+##### Query Handler
+
+The query handler receives all read relevant operations. These can either be query or simple `getById` calls.
+When receiving a query it will proceed by passing this to the repository which will call the database and return the dataset.
+If a request calls for a specific id the call will, most of the times, be revalidated against the Event Store.
+This is achieved by triggering the projection to make sure that the last sequence of a id is loaded into the query view.
+
+> The query side has the option to dynamically check the Event Store for newer events on a certain id to make sure for consistent responses without delay.
+
+##### Query View
+
+The query view is responsible to query the storage layer with the request from the command handler.
+It is also responsible to execute authorization checks. To check if a request is valid and can be answered.
+
+### Storage Layer
+
+As Zitadel itself is built completely stateless only the storage layer is needed to persist states.
+The storage layer of Zitadel is responsible for multiple tasks. For example:
+
+- Guarantee strong consistency for the command side
+- Guarantee good query performance for the query side
+- Backup and restore operation for disaster recovery purpose
+
+Zitadel currently supports PostgreSQL.
+Make sure to read our [Production Guide](/self-hosting/manage/production#prefer-postgre-sql) before you decide on using one of them.
+
+<Callout>
+Zitadel v2 supported CockroachDB and PostgreSQL. Zitadel v3 only supports PostgreSQL. Please refer to [the mirror guide](/self-hosting/manage/cli/mirror) to migrate to PostgreSQL.
+</Callout>

apps/docs/content/concepts/architecture/solution.mdx

@@ -0,0 +1,73 @@
+---
+title: Zitadel's Deployment Architecture
+sidebar_label: Deployment Architecture
+---
+
+## High Availability
+
+Zitadel can be run as high available system with ease.
+Since the storage layer takes the heavy lifting of making sure that data in synched across, server, data centers or regions.
+
+Depending on your projects needs our general recommendation is to run Zitadel across multiple availability zones in the same region or across multiple regions.
+Make sure to read our [Production Guide](/self-hosting/manage/production#prefer-postgre-sql) before you decide to use it.
+Consult the [Postgres documentation](https://www.postgresql.org/docs/) for more details.
+
+## Scalability
+
+Zitadel can be scaled in a linear fashion in multiple dimensions.
+
+- Vertical on your compute infrastructure
+- Horizontal in a region
+- Horizontal in multiple regions
+
+Our customers can reuse the same already known binary or container and scale it across multiple server, data center and regions.
+To distribute traffic an already existing proxy infrastructure can be reused.
+Simply steer traffic by path, hostname, IP address or any other metadata to the Zitadel of your choice.
+
+> To improve your service quality we recommend steering traffic by path to different Zitadel deployments
+> Feel free to [contact us](https://zitadel.com/contact/) for details
+
+## Example Deployment Architecture
+
+### Single Cluster / Region
+
+A Zitadel Cluster is a highly available IAM system with each component critical for serving traffic laid out at least three times.
+Our storage layer (Postgres) is built for single region deployments.
+Hence our reference design for Kubernetes is to have three application nodes and one storage node.
+
+> If you are using a serverless offering like Google Cloud Run you can scale Zitadel from 0 to 1000 Pods without the need of deploying the node across multiple availability zones.
+
+![](../../../public/img/zitadel_cluster_architecture.png)
+
+### Multi Cluster / Region
+
+To scale Zitadel across regions it is recommend to create at least three clusters.
+Each cluster is a fully independent ZITADEL setup.
+To keep the data in sync across all clusters, we recommend using Postgres with read-only replicas as a storage layer.
+Make sure to read our [Production Guide](/self-hosting/manage/production#prefer-postgre-sql) before you decide to use it.
+Consult the [Postgres documentation](https://www.postgresql.org/docs/current/high-availability.html) for more details.
+
+![](../../../public/img/zitadel_multicluster_architecture.png)
+
+## Zero Downtime Updates
+
+Since an Identity system tends to be a critical piece of infrastructure, the "in place zero downtime update" is a well needed feature.
+Zitadel is built in a way that upgrades can be executed without downtime by just updating to a more recent version.
+
+The common update involves the following steps and do not need manual intervention of the operator:
+
+- Keep the old version running
+- Deploy the version in parallel to the old version
+- The new version will start ...
+  - by updating databases schemas if needed
+  - participate in the leader election for background jobs
+- As soon as the new version is ready to accept traffic it will signal this on the readiness endpoint `/debug/ready`
+- At this point your network infrastructure can send traffic to the new version
+
+Users who use [Kubernetes/Helm](/self-hosting/deploy/kubernetes) or serverless container services like Google Cloud Run can benefit from the fact the above process is automated.
+
+<Callout>
+As a good practice we recommend creating Database Backups prior to an update.
+It is also recommend to read the release notes on GitHub before upgrading.
+Since Zitadel utilizes Semantic Versioning Breaking Changes of any kind will always increase the major version (e.g Version 2 would become Version 3).
+</Callout>

apps/docs/content/concepts/eventstore/implementation.mdx

@@ -0,0 +1,94 @@
+---
+title: ZITADEL Database Structure
+sidebar_label: Database Structure
+---
+
+This documentation gives you an insight into the structure of the ZITADEL database.
+The goal is to give you a rough overview, so you know where which data is stored and which database schemas and tables are used.
+
+## Event
+
+The single source of truth of ZITADEL are the events that are stored in the eventstore.
+From these events all different kind of resources e.g Users, Projects, Applications, etc. can be computed.
+
+An event has the following data:
+
+| Attribute | Description | Example |
+| --- | --- | --- |
+| id | unique identifier of the event, this is generated by the database  | b6402a60-e4655-4cc0-904b-f5c6760c4406 |
+| aggregate_type | the type of the aggregate, an aggregate can be compared to a resource or an object. One aggregate contains multiple event types | user |
+| aggregate_id | The unique identifier of an aggregate, this is generated by ZITADEL and is a sonyflake id | 168096909691353697 |
+| aggregate_version | The aggregate version shows in which version of the aggregate the event was created. This is needed to be able to compute correct objects | v1 |
+| event_type | The type of the event | user.human.added |
+| event_sequence | The event sequence is a sequence number that is incremented by one for each event on the instance. For technical reasons, a number can be omitted in some cases. This is needed so that the sequence of the events can be ensured. | 1234 |
+| previous_aggregate_sequence| This number is the sequence of the event last created on this specific aggregate. E.g. Last user with specific aggregate_id | 1233|
+| previous_aggregate_type_sequence | This number is the sequence of the event last created on this aggregate. E.g Last User | 1230 |
+| creation_date| timestamp when the event was created | 2022-07-05 13:57:56.358774+00 |
+| editor_user| The editor user contains mostly an unique identifier of a user. And tells who did the request that led to this event. Sometimes this can also be a name of a system within ZITADEL. | 165460784409638965, NOTIFICATION, LOGIN |
+| editor_service | The service defines which API was called when the event got created. If the event was created from the system itself this is empty. | Admin-API |
+| resource_owner | The resource owner defines to which organization/resource_owner the event belongs. This is an id generated by ZITADEL as sonyflake id | 168051083313153168 |
+| instance_id | ZITADEL is capable of containing multiple ZITADEL instances withing the system. This id is the unique identifier of the Instance and is generated by ZITADEL as sonyflake id. | 165460784409737865 |
+
+## Schemas
+
+| Schema | Description | Examples |
+| --- | --- | --- |
+| System | The system contains everything that is needed outside the ZITADEL instances.  | assets, encryption_key |
+| Eventstore | Eventstore is the base of ZITADEL and is the single source of truth. All the events stored in the eventstore can be used to generate different projections. | events, instance sequences, system wide unique constraints
+| Projections| The projections contain all the computed objects which are used for reading requests. | users, projects, etc|
+| Auth | This contains projections which are used for the auth api. All projections in this schema should be moved to Projections soon | users, auth_request, etc. |
+| Adminapi | This contains projections which are used for the admin api. All projections in this schema should be moved to Projections soon | styling|
+| Notification | This contains projections which are used for sending notification. All projections in this schema should be moved to Projections soon | styling|
+
+## Projections
+
+The projections in ZITADEL contain all the computed objects, that are used for the reading requests.
+It is possible that the projections are slightly behind the actual event and not all objects are up-to-date.
+
+### Pub-Sub
+To keep the projections as up-to-date as possible, an internal pub-sub system is used.
+As soon as an event is written to the event store, it is sent to the projections that have subscribed to this aggregate.
+
+### Spooler
+It is sometimes possible for technical reasons that not all events were sent to the projections.
+For this reason, a spooler runs in parallel, which checks every n minutes whether there are new events that have not yet been processed.
+
+### Current Sequence
+
+To ensure that no events get missed when creating the Projections, ZITADEL stores the current sequence, that was processed.
+You can find the current sequence in the following tables:
+- projections.current_sequences
+- notification.current_sequences
+- auth.current_Sequences
+- adminapi.current_sequences
+
+The current sequence is stored for each ZITADEL instance and table.
+
+| Attribute | Description | Examples |
+| --- | --- | --- |
+| projection_name | The name of the projection for which the sequence is valid.  | projection.users |
+| aggregate_type | The aggregate type where the sequence was from | user |
+| current_sequence | The sequence that was last processed | 1234 |
+| instance_id | The instance to which the event belongs | 165460784409737834 |
+| timestamp | Timestamp when the table was updated | 2022-07-05 13:57:59.454798+00 |
+
+### Failed Events
+
+Sometimes an event cannot be processed correctly for some reason and an error occurs.
+The event is then tried to be processed n times.
+When a defined number of attempts have failed, the event is stored in the Failed Events Table and the next event is processed.
+This must be done so that the projection is not blocked and no further events are processed.
+
+You can find the failed_events in the following tables:
+- projections.failed_events
+- notification.failed_events
+- auth.failed_events
+- adminapi.failed_events
+
+| Attribute | Description | Examples |
+| --- | --- | --- |
+| projection_name | The name of the projection for which the failed event should have been processed.  | projection.users |
+| failed_sequence | The sequence of the event that failed | 1234 |
+| failure_count | The number of times the event was attempted to be processed. If the number is lower than the max. attempts the event could be processed, but not on the first attempt | 5 |
+| error | The error message that occurred when the event could not be processed | User not found |
+| instance_id | The instance to which the event belongs | 165460784409737834 |

apps/docs/content/concepts/eventstore/overview.mdx

@@ -0,0 +1,53 @@
+---
+title: ZITADEL Event Store
+sidebar_label: Overview
+---
+
+ZITADEL is built on the [Event Sourcing pattern](../architecture/software), where changes are stored as events in an Event Store.
+
+## What is an Event Store?
+
+Traditionally, data is stored in relations as a state
+
+- A request needs to know the relations to select valid data
+- If a relation changes, the requests need to change as well
+- That is valid for actual, as well as for historical data
+
+An Event Store on the other hand stores events, meaning every change that happens to any piece of data relates to an event.
+The data is stored as events in an append-only log.
+
+- Think of it as a ledger that gets new entries over time, accumulative
+- To request data, all you have to do is to sum the events as the summary reflects the actual state
+- To investigate past changes to your system, you just select the events from your time range of interest
+- That makes audit/analytics very powerful, due to the historical data available to build queries
+
+## Benefits
+
+- Audit: You have a built-in audit trail that tracks all changes over an unlimited period of time.
+- Travel back in time: With our way of storing data we can show you all of your resources at a given point in time.
+- Future Projections: It is easy to compute projections with new business logic by replaying all events since installation.
+
+## Definitions
+
+Event Sourcing has some specific terms that are often used in our documentation. To understand how ZITADEL works it is important to understand this key definitions.
+
+### Events
+
+An event is something that happens in the system and gets written to the database. This is the single source of truth.
+Events are immutable and the current state of your system is derived from the events.
+
+Possible Events:
+- user.added
+- user.changed
+- product.added
+- user.password.checked
+
+### Aggregate
+
+An aggregate consist of multiple events. All events together from an aggregate will lead to the current state of the aggregate.
+The aggregate can be compared with an object or a resources. An aggregates should be used as transaction boundary.
+
+### Projections
+
+Projections contain the computed objects, that will be used on the query side for all the requests.
+Think of this as a normalized view of specific events of one or multiple aggregates.

apps/docs/content/concepts/features/account-linking.mdx

@@ -0,0 +1,37 @@
+---
+title: Account linking
+---
+
+ZITADEL supports linking user accounts from different external identity providers, such as social logins or enterprise IdPs, to a single ZITADEL user profile. This enables users to be recognized as the same user in your applications, regardless of which external account they use to log in.
+
+Each user in ZITADEL has one account for streamlined access management and a unified audit trail. Multiple external identities can be linked to this account.
+
+### Advantages
+
+- Users can log in with several identity providers without maintaining separate profiles
+- Already registered users can link additional external profiles
+- Provides backup authentication methods if an IdP is unavailable
+- Enables unified auditing across all linked identities
+
+### How it works
+
+Account linking is controlled by your organization and identity provider configuration.
+
+When external identity providers (such as social logins or enterprise SSO) are configured, a user account is created in ZITADEL, and the [external identity](../structure/users#federated-users) is linked to the ZITADEL account.
+
+> **Important:** If a user account in ZITADEL is already linked to an external identity and the user enters their username during login, ZITADEL will automatically redirect to the linked external identity provider for authentication.
+> There is **no choice** presented to the user between authenticating with local username/password and an external IDP once accounts are linked.
+> Only if the external login fails (for example, due to an expired or invalid IDP secret), will ZITADEL fall back to local authentication.
+
+Users are only shown options to pick local login or possible external IDPs **during registration**—that is, only when there is no existing account. For existing accounts that are linked to an external IDP, the system determines the authentication method automatically.
+
+If only one external identity provider is configured and username/password login is disabled, all authentication requests are immediately redirected to the external provider.
+
+In cases where a local account exists and a user registers or logs in through an external identity provider, ZITADEL can be instructed to link the new external identity to the local account based on matching criteria (such as email address or username).
+
+### Automatic account linking
+
+You can configure your identity provider to allow automatic account linking for users with the same email or username.
+To enable this, set "Account linking allowed" in the [identity provider template settings](/guides/integrate/identity-providers/introduction#key-settings-on-the-templates).
+
+Automatic account linking helps users associate multiple login options with their ZITADEL account, offering flexibility—however, at login, the authentication method will be determined by the link, **not by user choice**.

apps/docs/content/concepts/features/actions.mdx

@@ -0,0 +1,39 @@
+---
+title: ZITADEL Actions
+sidebar_label: Actions
+---
+
+By using ZITADEL actions, you can manipulate ZITADELs behavior on specific Events.
+This is useful when you have special business requirements that ZITADEL doesn't support out-of-the-box.
+
+<Callout>
+We're working on Actions continuously. In the [roadmap](https://zitadel.com/roadmap), you see how we are planning to expand and improve it. Please tell us about your needs and help us prioritize further fixes and features.
+</Callout>
+
+## Why actions?
+ZITADEL can't anticipate and solve every possible business rule and integration requirements from all ZITADEL users. Here are some examples:
+- A business requires domain specific data validation before a user can be created or authenticated.
+- A business needs to automate tasks. Roles should be assigned to users based on their ADFS 2016+ groups.
+- A business needs to store metadata on a user that is used for integrating applications.
+- A business needs to restrict the users who are allowed to register to a certain organization by their email domains.
+
+With actions, ZITADEL provides a way to solve such problems.
+
+## How it works
+Using the actions feature, *ORG_OWNERs* create a flow for each supported flow type.
+Each flow type provides its own events.
+You can hook into these events by assigning them an action.
+An action is composed of
+* a name,
+* a custom JavaScript code snippet,
+* an execution timeout in seconds,
+* a switch that defines if its corresponding flow should fail if the action fails.
+
+Within the JavaScript code, you can read and manipulate the state.
+
+## Further reading
+
+- [Assign users a role after they register using an external identity provider](/guides/manage/customize/behavior)
+- [Actions reference](/guides/manage/console/actions-overview)
+- [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
+- [Example use cases](/apis/actions/code-examples)

apps/docs/content/concepts/features/actions_v2.mdx

@@ -0,0 +1,64 @@
+---
+title: ZITADEL Actions v2
+sidebar_label: Actions v2
+---
+
+By using ZITADEL Actions v2, you can modify ZITADEL's behavior on specific API calls, events, or functions. This is useful when you have special business requirements that ZITADEL does not support out-of-the-box.
+
+<Callout>
+We're working on Actions continuously. In the [roadmap](https://zitadel.com/roadmap), you can see how we plan to expand and improve this feature. Please tell us about your needs to help us prioritize further improvements and features.
+</Callout>
+
+<Callout>
+To use Actions v2, activate the "Actions" [feature flag](/reference/api/feature/zitadel.feature.v2.FeatureService.SetInstanceFeatures) in order to manage the related resources.
+
+Actions v2 will always be executed if available, even if the feature flag is switched off. To remove any Actions v2, the related Execution must be removed.
+</Callout>
+
+## Why Actions?
+ZITADEL can't anticipate or solve every possible business rule and integration requirement for all users. Here are some examples:
+- A business requires domain-specific data validation before a user can be created or authenticated.
+- A business needs to automate tasks, such as assigning roles to users based on their ADFS 2016+ groups.
+- A business needs to store metadata on a user, which is used for integrating applications.
+- A business needs to restrict which users are allowed to register to a certain organization by their email domains.
+
+With Actions, ZITADEL provides a way to address such scenarios.
+
+## How it works
+There are three necessary components:
+- **Endpoint:** An external endpoint with the desired logic. It can be anything, as long as it can receive an HTTP POST request.
+- **Target:** A resource in ZITADEL containing all the necessary information about how to trigger an endpoint.
+- **Execution:** A resource in ZITADEL specifying when to trigger which targets.
+
+The process is that, at certain points, ZITADEL executes a defined Execution, which then calls the defined Target(s). This allows everyone to implement custom behavior for as many processes as needed.
+
+Possible conditions for the Execution:
+- **Request:** Reacts to or manipulates requests to ZITADEL, for example, by adding information to newly created users.
+- **Response:** Reacts to or manipulates responses from ZITADEL, for example, provisioning newly created users to other systems.
+- **Function:** Reacts to various functions in ZITADEL, replacing [Actions](/concepts/features/actions).
+- **Event:** Reacts to different events created in ZITADEL, for example, to inform someone if a user gets locked.
+
+<Callout>
+Currently, defined Actions v2 will be executed in addition to [Actions](/concepts/features/actions).
+</Callout>
+
+## Migration
+
+- [Migrate Actions v1 to Actions v2](/guides/integrate/actions/migrate-from-v1)
+
+## Further reading
+
+- [Actions v2 reference](/guides/integrate/actions/usage)
+- [Actions v2 example execution for request](/guides/integrate/actions/testing-request)
+- [Actions v2 example execution for request manipulation](/guides/integrate/actions/testing-request-manipulation)
+- [Actions v2 example execution for request signature check](/guides/integrate/actions/testing-request-signature)
+- [Actions v2 example execution for response](/guides/integrate/actions/testing-response)
+- [Actions v2 example execution for response manipulation](/guides/integrate/actions/testing-response-manipulation)
+- [Actions v2 example execution for function](/guides/integrate/actions/testing-function)
+- [Actions v2 example execution for function manipulation](/guides/integrate/actions/testing-function-manipulation)
+- [Actions v2 example execution for event](/guides/integrate/actions/testing-event)
+
+## Example use cases:
+The following repository contains various examples demonstrating how to use Actions v2 in different scenarios. It also includes a deployment script for testing the examples with Cloudflare Workers:
+
+- [Actions v2 examples](https://github.com/zitadel/actions/tree/main/actions-v2-cloudflare-workers)

apps/docs/content/concepts/features/audit-trail.mdx

@@ -0,0 +1,56 @@
+---
+title: ZITADEL's In-built Audit Trail
+sidebar_label: Audit Trail
+---
+
+ZITADEL provides you with an built-in audit trail to track all changes and events over an unlimited period of time.
+Most other solutions replace a historic record and track changes in a separate log when information is updated.
+ZITADEL only ever appends data in an [Eventstore](/concepts/eventstore/overview), keeping all historic record.
+The audit trail itself is identical to the state, since ZITADEL calculates the state from all the past changes.
+
+![](../../../public/img/concepts/audit-trail/audit-log-events.png)
+
+This form of audit log has several benefits over storing classic audit logs.
+You can view past data in-context of the whole system at a single point in time.
+Reviewing a past state of the application can be important when tracing an incident that happened months back. Moreover the eventstore provides a truly complete and clean audit log.
+
+<Callout title="Future Plans">
+There will be three major areas for future development on the audit data
+
+- [Metrics](https://github.com/zitadel/zitadel/issues/4458) and [standard reports](https://github.com/zitadel/zitadel/discussions/2162#discussioncomment-1153259)
+- [Feedback loop](https://github.com/zitadel/zitadel/issues/5102) and threat detection
+- Forensics and replay of events
+
+</Callout>
+
+## Accessing the Audit Log
+
+### Last changes of an object
+
+You can check the last changes of most objects in the [Console](/guides/manage/console/console-overview).
+In the following screenshot you can see an example of last changes on an [user](/guides/manage/console/users-overview).
+The same view is available on several other objects such as organization or project.
+
+![](../../../public/img/guides/console/myprofile.png)
+
+### Event View
+
+Administrators can see all events across an instance and filter them directly in [Console](/guides/manage/console/overview).
+Go to your default settings and then click on the Tab **Events** to open the Event Viewer or browse to $CUSTOM_DOMAIN/ui/console/events
+
+![](../../../public/img/concepts/audit-trail/event-viewer.png)
+
+### Event API
+
+Since everything that is available in Management Console can also be called with our APIs, you can access all events and audit data trough our APIs:
+
+- [Event API Guide](/guides/integrate/zitadel-apis/event-api)
+- [API Documentation](/reference/api/admin)
+
+Access to the API is possible with a [Service User](/guides/integrate/service-users/authenticate-service-users) account, allowing you to integrate the events with your own business logic.
+
+## Using logs in external systems
+
+You can use the events from the audit log in external systems such as a SOC/SIEM solution.
+
+Follow our guide on how to [integrate ZITADEL with external systems for streaming events and audit logs](/guides/integrate/external-audit-log).

apps/docs/content/concepts/features/console.mdx

@@ -0,0 +1,33 @@
+---
+title: "ZITADEL Management Console: Resource management and customization"
+sidebar_label: Management Console
+---
+
+The ZITADEL management console is a web-based interface designed to facilitate the management and administration of ZITADEL resources and configurations.
+It serves as a central hub where administrators can perform various tasks related to identity and access management within their organization's infrastructure.
+
+The management console is available by navigating to the [custom domain](/concepts/features/custom-domain) of your instance and appending the path `/ui/console`.
+Administrators can [restrict end-users from accessing the management console](/guides/solution-scenarios/restrict-console).
+
+Here's an overview of what the management console enables users to do:
+
+1. **Default Settings:** [Managers](/concepts/structure/managers) can access and manage the default settings of the ZITADEL system. This includes configuring authentication methods, security policies, and other system-wide parameters to meet the organization's requirements.
+
+2. **Resource Management:** The management console allows for the creation, updating, and deletion of essential resources such as organizations, users, projects, and applications. Administrators can efficiently manage these entities to ensure proper access control and governance.
+
+3. **User Management:** Administrators can manage user accounts, including creating new user accounts, updating user profiles, resetting passwords, and deactivating or deleting user accounts as needed.
+
+4. **Access Control:** The management console provides tools for defining and managing access control policies. This includes assigning roles and permissions to users, configuring fine-grained access controls, and managing access to specific resources.
+
+5. **Audit Logging:** The management console offers access to [audit logs](/concepts/features/audit-trail) that track user activity and changes made to resources and system settings. Administrators can review these logs to monitor security-related events, track changes, and maintain compliance with regulatory requirements.
+
+6. **Customization and Branding:** The management console allows organizations to customize the branding and appearance of their ZITADEL instance. This includes uploading custom logos, selecting color schemes, and applying other visual customizations to align the interface with the organization's branding guidelines.
+
+7. **Manager Assignment:** Administrators can assign ZITADEL [managers](/concepts/structure/managers) who have elevated privileges for managing resources within the organization. This allows for the delegation of administrative tasks while maintaining proper oversight and control.
+
+Overall, the ZITADEL management console serves as a comprehensive tool for administrators to configure, manage, and monitor identity and access management within their organization, providing the necessary controls to ensure security, compliance, and efficient administration of resources.
+
+Notes:
+
+- Detailed guide on [using the management console](/guides/manage/console/console-overview)
+- [Restrict access](/guides/solution-scenarios/restrict-console) to the management console

apps/docs/content/concepts/features/custom-domain.mdx

@@ -0,0 +1,13 @@
+---
+title: Custom Domain
+sidebar_label: Custom Domain
+---
+
+A ZITADEL Custom Domain refers to the ability for organizations to personalize the authentication experience by using their own domain name rather than the default ZITADEL domain.
+
+This feature allows organizations to maintain their brand identity throughout the authentication process, providing a seamless and consistent user experience.
+By configuring a Custom Domain within ZITADEL, organizations can replace the default authentication URLs with their own domain, such as "login.example.com" or "auth.companyname.com".
+
+This not only enhances the overall user experience but also reinforces the organization's brand presence. Additionally, Custom Domains can contribute to trust and credibility, as users are more likely to recognize and trust URLs associated with the organization rather than generic domains. Overall, ZITADEL's Custom Domain feature empowers organizations to tailor the authentication process to align with their brand identity and user expectations.
+
+Learn how to [configure a Custom Domain in ZITADEL Cloud](/guides/manage/cloud/instances#add-custom-domain) or how to configure [Custom Domain when self-hosting](/self-hosting/manage/custom-domain).

apps/docs/content/concepts/features/external-user-grant.mdx

@@ -0,0 +1,40 @@
+---
+title: External user grant
+---
+
+ZITADEL's external user grant is a feature that allows you to grant access to projects within your organization to users from other organizations.
+This is useful in scenarios where you want to collaborate with external users without needing them to be part of your organization.
+By using external user grants, you can streamline collaboration with external users while maintaining control over access to your projects within ZITADEL.
+
+![](../../../public/img/concepts/features/external-user-grant.png)
+
+## Where to store users
+
+### Consumer Identity Management (CIAM) / Business-to-Consumer (B2C)
+
+You might typically store all users in a single ZITADEL [organization](../structure/organizations) for managing customer accounts.
+We recommend creating a second organization for your own team that also contains all the projects and applications that will be [granted](../structure/granted_projects) to the first organization with the B2C customer accounts.
+Instead of duplicating user accounts for your team members in the B2C organization, you can create external user grants on the B2C organization.
+
+### Multitenancy / Business-to-Business (B2B)
+
+ZITADEL allows you to create separate [organizations](../structure/organizations) for each of your business partner or tenant.
+There might be cases were users from one organization need access to projects from another organization.
+You can create an external user grant, that allows the inviting organization to manage the roles for the external user.
+
+## Project Grants vs. User Grants
+
+Project grants are used to delegate access management of an entire project (or specific roles of the project) to another organization.
+
+User grants provide a more granular approach, allowing specific users from external organizations to access your projects.
+
+## Alternative to multiple user accounts
+
+A user account is always unique across a ZITADEL instance.
+In some use cases, external user grants are a simple way to allow users access to multiple tenants.
+
+## References
+
+* [API reference for user grants](/reference/api/management)
+* [How to manage user grants through ZITADEL's management console](/guides/manage/console/roles#authorizations)
+* [More about multi-tenancy with ZITADEL](https://zitadel.com/blog/multi-tenancy-with-organizations)

apps/docs/content/concepts/features/identity-brokering.mdx

@@ -0,0 +1,78 @@
+---
+title: Identity Brokering
+sidebar_label: Identity Brokering
+---
+
+Link social logins and external identity providers with your identity management platform allowing users to login with their preferred identity provider.
+
+Establish a trusted connection between your central identity provider (IdP) and third party identity providers.
+
+By using a central identity brokering service you don't need to develop and establish a trust relationship between each application and each identity provider individually.
+
+## What are federated identities?
+
+Federated identity management is an arrangement built upon the trust between two or more domains. Users of these domains are allowed to access applications and services using the same identity.
+This identity is known as federated identity and the pattern behind this is identity federation.
+
+Compatibility across various IdPs is ensured by using industry standard protocols, such as:
+
+* OpenID Connect (OIDC): A modern and versatile protocol for secure authentication.
+* SAML2: A widely adopted protocol for secure single sign-on (SSO) in enterprise environments.
+* LDAP: A lightweight protocol for accessing user data directories commonly used in corporate networks.
+
+## What is identity brokering?
+
+A service provider that specializes in brokering access control between multiple service providers (also referred to as relying parties) is called an identity broker.
+Federated identity management is an arrangement that is made between two or more such identity brokers across organizations.
+
+For example, if Google is configured as an identity provider in your organization, the user will get the option to use his Google Account on the Login Screen of ZITADEL.
+Because Google is registered as a trusted identity provider, the user will be able to login in with the Google account after the user is linked with an existing ZITADEL account (if the user is already registered) or a new one with the claims provided by Google.
+
+![](../../../public/img/concepts/features/identity-brokering.png)
+
+The schema is a very simplified version, but shows the essential steps for identity brokering
+
+1. An unauthenticated user wants to use the alpha.com's application.
+2. The application redirects the user to alpha.com's identity provider (IdP).
+3. Based on the user's tenants configuration the IdP presents the configured identity providers, or redirects the user directly to the primary external IdP. The user authenticates with their external identity provider (eg, Entra ID).
+4. After the authentication, the user is redirected back to alpha.com's identity provider. If the user doesn't exist in the IdP the user will be created just-in-time and linked to the external identity provider for future reference.
+5. As with a local authentication, the IdP issues a token to the user that can be used to access the application. The IdP redirects the user, which is now authenticated, eventually to the application.
+
+## Is single-sign-on (SSO) the same as identity brokering?
+
+Sometimes single-sign-on (SSO) and login with third party identity providers is used interchangeably.
+Typically SSO describes an authentication scheme that allows users to log in once at a central identity provider and access service providers (client applications) without to login again.
+
+Identity brokering describes an authentication scheme where users can login with external identity providers that have a established trust with an identity provider which facilitates the authentication for the requested applications.
+
+The connection between the two lies in how SSO can be implemented as part of an identity brokering solution.
+In such cases, the identity broker uses SSO to enable seamless access across multiple systems, handling the complexities of different authentication protocols and standards behind the scenes.
+This allows users to log in once and gain access to multiple systems that the broker facilitates.
+
+## Multitenancy and identity brokering
+
+In a multi-tenancy application, you want to be able to configure an external identity provider per tenant.
+For example some organizations might use their EntraID, some other want to login with their OKTA, or Google Workspace.
+
+Using an identity provider with strong multitenancy capabilities such as ZITADEL, you can configure a different set of external identity providers per organization.
+
+[Domain discovery](/guides/solution-scenarios/domain-discovery) ensures that users are redirected to their external identity provider based on their email-address or username.
+[Managers](../structure/managers) can configure organization domains that are used for domain-based redirection to an external IdP.
+
+![](../../../public/img/concepts/features/domain-discovery.png)
+
+## Simplify identity brokering with ZITADEL templates
+
+ZITADEL works with SAML, OpenID Connect, and LDAP external identity providers.
+
+For popular IdPs such as EntraID, Okta, Google, Facebook, and GitHub, ZITADEL [offers pre-configured templates](/guides/integrate/identity-providers/introduction).
+These templates expedite the configuration process, allowing organizations to quickly integrate these providers with minimal effort.
+
+ZITADEL recognizes that specific needs may extend beyond pre-built templates.
+To address this, ZITADEL provides generic templates that enable connection to virtually any IdP.  This ensures maximum flexibility and future-proofs login infrastructure, accommodating future integrations with ease.
+
+### References
+
+* [Detailed integration guide for many identity providers](/guides/integrate/identity-providers/introduction)
+* [Setup identity providers with Management Console](/guides/manage/console/default-settings#identity-providers)
+* [Configure identity providers with the ZITADEL API](/reference/api/management)

apps/docs/content/concepts/features/index.mdx

@@ -0,0 +1,14 @@
+---
+title: Features
+---
+
+<Cards >
+  <Card  href="/concepts/features/identity-brokering" title="Identity Brokering" />
+  <Card  href="/concepts/features/account-linking" title="Account Linking" />
+  <Card  href="/concepts/features/selfservice" title="Self Service" />
+  <Card  href="/concepts/features/custom-domain" title="Custom Domain" />
+  <Card  href="/concepts/features/audit-trail" title="Audit Trail" />
+  <Card  href="/concepts/features/passkeys" title="Passkeys" />
+  <Card  href="/concepts/features/actions" title="Actions" />
+  <Card  href="/concepts/features/console" title="Console" />
+</Cards>

apps/docs/content/concepts/features/passkeys.mdx

@@ -0,0 +1,38 @@
+---
+title: "Passkeys in ZITADEL: Passwordless phishing-resistant authentication"
+sidebar_label: Passkeys
+---
+
+ZITADEL's passkeys feature enables passwordless authentication, offering a **smoother and more secure** login experience for your users. This document explains the essential details for developers.
+
+### What are Passkeys?
+
+Imagine signing in without passwords! Passkeys, replacing traditional passwords, leverage **public-key cryptography** similar to FIDO2 and WebAuthn. Users rely on their devices' **biometrics or PINs** for authentication, eliminating password burdens.
+
+### Benefits for Developers
+
+* **Enhanced Security:** Phishing-resistant passkeys minimize credential theft risks.
+* **Streamlined User Experience:** Faster, easier logins free users from managing passwords.
+* **Platform Agnostic:** Works across devices and platforms supporting passkeys.
+* **Modern Standard:** Complies with the FIDO2 and WebAuthn standards.
+
+### Features
+
+* **Seamless Registration:** Create unique passkeys for users on various devices. Optionally pair them with specific users and choose cross-platform or platform-specific options.
+* **User Control:** Users manage their passkeys directly through ZITADEL's self-service portal, allowing registration, viewing, and deletion.
+* **Intuitive Login:** Users initiate passkey login by selecting the passkey option and verifying themselves with the device's biometrics (fingerprint, face ID, etc.).
+* **Intuitive Login:** Users initiate passkey login by selecting the passkey option and verifying themselves with the device's biometrics (fingerprint, face ID, etc.).
+* **Robust Fallback:** Traditional password login remains available for users without passkeys.
+
+### Developer Resources
+
+* **Documentation:** Passkeys Guide: [https://zitadel.com/docs/guides/integrate/login-ui/passkey](/guides/integrate/login-ui/passkey)
+* [Create Passkey Registration Link API](/guides/manage/user/reg-create-user)
+
+### Notes
+
+* Passkey support is still evolving in browsers and platforms. Check compatibility for your target audience.
+* ZITADEL actively develops its passkey features. Stay updated with documentation and releases.
+* Passkeys are bound to your domain, thus we recommend configuring a [Custom Domain](/concepts/features/custom-domain) before setting up passkeys.
+
+Don't hesitate to ask if you have further questions about integrating passkeys in your ZITADEL application!

apps/docs/content/concepts/features/selfservice.mdx

@@ -0,0 +1,156 @@
+---
+title: Self Service in ZITADEL
+sidebar_label: Self Service
+---
+
+ZITADEL allows users to perform many tasks themselves.
+For these tasks we either provide a user interface, or the tasks can be initiated or completed through ZITADEL's APIs.
+
+It is important to understand that, depending on your use case, there will exist different user-types that want to perform different actions:
+
+- `Users` are the end-users of your application. Like with any CIAM solution, users should be able to perform tasks like register/join, update their profile, manage authenticators, etc. There are certain actions that can be executed pre-login, yet others require the user to have a valid session.
+- `Managers` are users with a [special administrator role](../../guides/manage/console/managers) within ZITADEL and can perform administrative actions such as system configuration or granting access rights to users.
+
+All self-service interfaces are available in different [languages](/guides/manage/customize/texts#internationalization-i-18-n).
+
+<Callout>
+ZITADEL covers the typical "CIAM" self-service capabilities as well as delegated access management for multi-tenancy scenarios. Please refer to the section [Managers](#managers).
+</Callout>
+
+## Registration
+
+<Callout>
+You can pre-select a given organization by passing the scope `urn:zitadel:iam:org:domain:primary:{domainname}` in the authorization request.
+This will force users to register only with the specified organization.
+Furthermore, the branding and login settings (e.g., Social Login Providers) are directly shown to the user.
+</Callout>
+
+### Local account
+
+Allows anonymous users and authenticated users, who are not yet in the given organization, to create an account (register) themselves.
+
+- Mandatory profile fields
+- Set password
+- Accept terms of service and privacy policy
+- User receives an email with a one-time code for verification purpose
+- User has to enter the one-time code to finish registration
+- User can re-request a new one-time code
+
+The user is prompted on the first login to set up MFA.
+This step can be made mandatory if MFA is enforced in the login policy.
+
+### Existing Identity / SSO / Social Login
+
+Anonymous users and authenticated users, who are not yet in the given organization, to register with an external identity provider.
+An external identity provider can be a Social Login Provider or a pre-configured identity provider.
+
+- Information from the external identity provider is used to pre-fill the profile information
+- User can update the profile information
+- An account is created within ZITADEL and linked with the external identity provider
+
+#### Account Linking
+
+When you log in with an external identity provider, and the user does not exist in ZITADEL, then an autoregister flow is triggered. The user is presented with two options:
+
+- Create a new account: A new account will be created as stated above
+- Autolink: The user is prompted to log in with an existing [local account](#local-account). If successful, the existing identity from the external identity provider will be linked with the local account. A user can now log in with either the local account or any of the linked external accounts.
+
+## Login
+
+### SSO / Social Logins
+
+Given an external identity provider is configured on the instance or on the organization, then:
+
+- the user will be shown a button for each identity provider as an alternative to log in with a [local account](#local-account)
+- when clicking the button, the user will be redirected to the identity provider
+- after successful login, the user will be redirected to the application
+
+### Machines
+
+Machine accounts can't use an interactive login but require other means of authentication, such as privately signed JWT or personal access tokens.
+Read more about [Service Users](/guides/integrate/service-users/authenticate-service-users) and recommended [OpenID Connect Flows](/guides/integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
+
+## Logout
+
+Users can terminate the session for all their users (logout).
+A client can also implement this by calling the [specific endpoint](/apis/openidoauth/endpoints#end-session-endpoint).
+
+## Profile
+
+These actions are available for authenticated users only.
+ZITADEL provides a self-service UI for the user profile out-of-the box under the path _$CUSTOM_DOMAIN/ui/console/users/me_.
+You can also implement your own version in your application by using our APIs.
+
+### Change password
+
+Users can change their passwords.
+The current password must be entered first.
+
+### MFA / FIDO Passkeys
+
+Users can set up and delete a second factor and FIDO Passkeys (Passwordless).
+Available authenticators are:
+
+- Time-based one-time password (TOTP) (Which are Authenticator Apps like Google/Microsoft Authenticator, Authy, etc.)
+- One-time password sent as E-Mail
+- One-time password sent as SMS
+- FIDO Universal Second Factor (U2F) (Security Keys, Device, etc.)
+- FIDO2 WebAuthN (Passkeys)
+
+### Update Information
+
+Users can change their profile information. This includes
+
+- UserName
+- First- and Last name
+- Nickname
+- Display Name
+- Gender
+- Language
+- Email address
+- Phone number
+
+### Email Verification
+
+Users can change their email address.
+The user receives a one-time password and can verify control over the given email address.
+
+### Phone Verification
+
+Users can change their phone number.
+The user receives a one-time password and can verify control over the given phone number.
+
+### Identity providers
+
+Users can create a connection between a [local user account](#local-account) and an [external identity](#existing-identity--sso--social-login).
+The user can log in with any of the linked accounts.
+[Linking of external accounts](#account-linking) is done during the login process.
+
+## Managers
+
+It is important to note that a `Manager` is not simply an administrative user, but can be used to create much more advanced scenarios such as delegating administration of a whole organization to a user, acting then as administrator and permission manager of that user group.
+
+Thus, we will explain service for two of the most common scenarios in ZITADEL:
+
+- `Managers in isolation`: Granting administrative permissions within a single organization context.
+- `Managers in delegation`: Granting administrative permissions to a user from a different organization where the organizations depend on each other
+
+A list of [Administrator Roles](../../guides/manage/console/managers#roles) is available with a description of permissions.
+Managers can be assigned to both human users and service users, e.g., for managing certain tasks programmatically.
+
+### Managers in isolation
+
+A user with Administrator roles `IAM_OWNER` or `ORG_OWNER` might want to assign other users from their organization elevated permissions to handle certain aspects of the IAM tasks.
+This could be permission to assign authorizations within this isolated organization (`ORG_USER_MANAGER`) or handling setup of projects and applications (`PROJECT_OWNER`).
+
+### Managers in delegation
+
+In a setup like described in the [B2B Scenario](/guides/solution-scenarios/b2b), there exists an organization of the project owner and a customer organization.
+The project is granted to the customer organization, such that the customer can access the project and assign authorization to their users.
+
+Given such as set up the owner might want to give one administrative user of the customer organization the role `ORG_OWNER`.
+Equipped with this Administrator Role, the user can perform actions like configuring their own SSO/Identity Provider, set security policy for their organization, customize branding, or assign project or Administrator roles to other users.
+
+An `ORG_OWNER` can also not only delegate Administrator roles to other users [as described in the earlier section](#managers-in-isolation) but also manage all aspects of their own organization as well as authorize users to use the granted project.
+With ZITADEL there is no need to replicate all settings and projects across organizations.
+Instead, you could set up the project in one organization, delegate it to different organizations, and then appoint users as Managers of that organization to allow for self-service in a multi-tenancy scenario.

apps/docs/content/concepts/index.mdx

@@ -0,0 +1,20 @@
+---
+title: "Key Concepts"
+description: "This part of our documentation contains ZITADEL specific or general concepts required to understand the system or our guides."
+---
+
+{/* THIS FILE IS AUTO-GENERATED FROM SIDEBAR-DATA.
+  ANY MANUAL CHANGES WILL BE OVERWRITTEN.
+*/}
+
+import { Card, Cards } from 'fumadocs-ui/components/card';
+import { FileText, Folder, Link as LinkIcon } from 'lucide-react';
+
+<Cards>
+    <Card title="Instance" href="/concepts/structure/instance" icon={<FileText />} />
+    <Card title="Organizations Overview" href="/guides/manage/console/organizations-overview" icon={<FileText />} />
+    <Card title="Projects Overview" href="/guides/manage/console/projects-overview" icon={<FileText />} />
+    <Card title="Applications Overview" href="/guides/manage/console/applications-overview" icon={<FileText />} />
+    <Card title="Users Overview" href="/guides/manage/console/users-overview" icon={<FileText />} />
+    <Card title="Managers" href="/concepts/structure/managers" icon={<FileText />} />
+</Cards>

apps/docs/content/concepts/knowledge/index.mdx

@@ -0,0 +1,7 @@
+---
+title: Knowledge
+---
+
+<Cards >
+  <Card  href="/concepts/knowledge/opaque-tokens" title="Opaque Tokens" />
+</Cards>

apps/docs/content/concepts/knowledge/opaque-tokens.mdx

@@ -0,0 +1,70 @@
+---
+title: "Opaque Tokens in Zitadel: Enhancing Application Security"
+sidebar_label: Opaque tokens
+---
+
+In the context of application security, robust authentication mechanisms are essential for safeguarding sensitive data and ensuring user trust.
+Opaque tokens, the default token type within the ZITADEL platform, play a crucial role in bolstering security measures.
+This documentation elucidates the principles behind opaque tokens, their implementation within ZITADEL, and their advantages over alternative token types.
+
+## What are Opaque Tokens?
+
+Opaque tokens are a type of access token utilized in authentication processes, particularly within OAuth 2.0 and OpenID Connect (OIDC) frameworks. Unlike self-contained tokens like [JSON Web Tokens (JWT)](https://datatracker.ietf.org/doc/html/rfc7519), opaque tokens do not divulge user information directly.
+Instead, they serve as opaque references to session data stored securely on the authorization server.
+
+## Authentication Workflow with Opaque Tokens
+
+1. **Token Generation**: When a user initiates an authentication process within an application integrated with ZITADEL, the authentication server generates a unique opaque token associated with the user's session.
+
+2. **Token Presentation**: The generated opaque token is provided to the client, which subsequently presents it during requests to access protected resources within the application.
+
+3. **Token Verification**: Upon receiving the opaque token, the application server interacts with the authorization server to validate its authenticity and retrieve detailed information about the user's session. This process ensures the integrity of the authentication flow and verifies the user's permissions to access requested resources.
+
+## Benefits of Opaque Tokens in ZITADEL
+
+1. **Reduced Token Exposure**: Opaque tokens mitigate the risk of token exposure since they do not contain sensitive user information directly. This reduces the likelihood of token-based attacks and enhances overall security posture.
+
+2. **Enhanced Server-side Control**: With opaque tokens, validation occurs server-side, granting administrators greater control over authentication flows and access policies. This centralized approach facilitates comprehensive monitoring and enforcement of security measures, including server-side single-logout across all applications.
+
+3. **Protection Against Token Tampering**: Opaque tokens prevent unauthorized manipulation of token contents, thereby ensuring the integrity and authenticity of authentication processes. This protection against token tampering further strengthens the security of applications integrated with ZITADEL.
+
+## Opaque Tokens vs. JWT Tokens
+
+When it comes to implementing authentication and authorization mechanisms within applications, developers often face the choice between different types of tokens, each with its own set of characteristics and advantages.
+Two common types of tokens used in authentication protocols are opaque tokens and JSON Web Tokens (JWT).
+
+### Structure
+
+- **Opaque Tokens**: Opaque tokens are essentially references or pointers to information stored on the authorization server. They do not contain any meaningful user data within the token itself. Instead, they typically consist of a unique identifier (e.g., a session ID or database key) that allows the server to look up the associated session information.
+
+- **JWT Tokens**: JSON Web Tokens, on the other hand, are self-contained tokens that contain user information in a JSON format. JWTs consist of three base64-encoded sections: header, payload, and signature. The payload contains claims or assertions about the user (e.g., user ID, roles, expiration time) that are digitally signed to ensure integrity.
+
+### Token verification
+
+- **Opaque Tokens**: Verifying opaque tokens requires interaction with the authorization server. When a client presents an opaque token to a resource server, the resource server sends the token to the authorization server for validation. The authorization server then checks the token's validity and returns the associated user information if the token is valid.
+
+- **JWT Tokens**: JWT tokens can be verified locally by clients without needing to communicate with the authorization server. Clients can validate JWT signatures using public keys or shared secrets obtained during the token issuance process. This decentralized verification process can be faster and more scalable but requires securely distributing and managing keys.
+
+### Token security and size
+
+- **Opaque Tokens**: Since opaque tokens do not contain user information, they are inherently more secure in terms of protecting sensitive data. However, the reliance on server-side validation means there is an overhead associated with each token verification request, which can impact performance in high-throughput scenarios.
+
+- **JWT Tokens**: JWT tokens contain user information within the token itself, which can be convenient for clients as it eliminates the need for frequent interactions with the authorization server. However, this also means that JWT tokens can potentially expose sensitive information if not handled and secured properly. Additionally, JWT tokens tend to be larger compared to opaque tokens due to the encoded payload.
+
+### Use cases and trade-offs
+
+- **Opaque Tokens**: Opaque tokens are well-suited for scenarios where security and confidentiality are top priorities, such as handling highly sensitive user data or complying with strict privacy regulations. They are particularly advantageous in distributed systems where centralized control over authentication and access policies is desired.
+
+- **JWT Tokens**: JWT tokens are often preferred in scenarios where performance and scalability are critical, such as microservices architectures or API-based applications. The ability to verify tokens locally can reduce latency and minimize dependencies on external services. However, developers must carefully consider the implications of including sensitive information in JWT payloads and implement appropriate security measures.
+
+## Conclusion
+
+In conclusion, opaque tokens represent a foundational component in fortifying application security within ZITADEL.
+By leveraging opaque tokens, organizations can establish robust authentication mechanisms, mitigate security risks, and maintain stringent control over access policies.
+As organizations navigate the complex landscape of application security, integrating technologies such as opaque tokens becomes imperative for safeguarding sensitive data and fostering user trust.
+
+Notes:
+
+- Read more about the differences in our [blog on JWT vs. Opaque tokens](https://zitadel.com/blog/jwt-vs-opaque-tokens)
+- Learn how to use [token introspection](/guides/integrate/token-introspection) to validate access tokens
+- Decode, verify and generate valid JWT tokens with [jwt.io](https://jwt.io/)

apps/docs/content/concepts/principles.mdx

@@ -0,0 +1,23 @@
+---
+title: Principles
+---
+
+## ZITADEL engineering and design principles
+
+- Be transparent about your decisions
+- Embrace stateless application design
+- System of records is the event store
+- Everything else needs to be able to be regenerated
+- Try not so solve complex problems outside of the IAM Domain
+- Use a scalable storage for the event store and read models
+- Try to be idempotent whenever possible
+- Reduce necessity of external systems or dependencies as much as possible
+- Embrace automation
+- Design API first
+- Optimize all components for day-two operations
+- Use only open source projects with permissive licenses
+- Don't roll your own crypto algorithm
+- Embrace (industry) standard as much as possible
+- Make use of platform features
+- Be able to run with a CDN and WAF
+- Releases utilized semantic versioning and release whenever feasible

apps/docs/content/concepts/structure/_manager_description.mdx

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

apps/docs/content/concepts/structure/_org_description.mdx

@@ -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}`).

apps/docs/content/concepts/structure/_project_description.mdx

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

apps/docs/content/concepts/structure/applications.mdx

@@ -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)

apps/docs/content/concepts/structure/granted_projects.mdx

@@ -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)

apps/docs/content/concepts/structure/index.mdx

@@ -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>

apps/docs/content/concepts/structure/instance.mdx

@@ -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)

apps/docs/content/concepts/structure/managers.mdx

@@ -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

apps/docs/content/concepts/structure/organizations.mdx

@@ -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).

apps/docs/content/concepts/structure/policies.mdx

@@ -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).

apps/docs/content/concepts/structure/projects.mdx

@@ -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)

apps/docs/content/concepts/structure/users.mdx

@@ -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)