chore(documentation): documentation and manuals for ZITADEL (#710)

* chore: cleanup old docs folder * remove docs path trigger * wip docs structure * chore: ignore site changes in ci * add manuals route * new structure * structure * Use correct title * remove trigger for code scan for static site generator * change names * add lorem ipsum to test styling * use h3 to deeplink * add site to dependabot * lint readme.md * remove not needed file * ignore site on pull request code scan * add initial contrib * Minor correction * Added section Developer & Integration * Changed link list layout, added labels, added translations * Added missing <li> tags * Added correct link to section Developer & Integration * Fixing list style * Overhauling description texts and translations * outline * teaser go * outline * wip * rework * wip * wip * wip * hop * wip * first draft for "administrate" done * init outline * fix deploy step * lint * commit wip * commit wip * md lint * Link * fix: path to edit (#711) * wip * wip * wip * what are... * use only features * wip docs * Update 00-user.en.md * project * uppercase en * wip * wip * wip * policies rework * improve text * correct typo * update readme * correct styling * add link to docs guides * make the linter happy * rename * wip * move api to own file * correct links and lint * wip roles and integration * add pkce * reduce padding and margin * wip scope and claims * wip claim & scopes * make the linter happy * insert links where possible * wip * wip roles & providers * Update README.md * Update 00-user.en.md * minor text improvements * use master branch to deploy * use proper ci file * Apply suggestions from code review Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com> Co-authored-by: Matthias M. Schneider <mati@matimax.info> Co-authored-by: Max Peintner <max@caos.ch> Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com>
2025-02-28 16:27:23 +00:00 · 2020-10-16 14:13:02 +02:00 · 2020-10-16 14:13:02 +02:00 · ef3b7482cd
commit ef3b7482cd
parent b1d61afc8f
70 changed files with 1143 additions and 221 deletions
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@ -24,3 +24,11 @@ updates:
  commit-message:
    prefix: chore
    include: scope
 - package-ecosystem: npm
  directory: "/site"
  schedule:
    interval: monthly
  open-pull-requests-limit: 10
  commit-message:
    prefix: chore
    include: scope
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@ -3,9 +3,13 @@ name: "Code scanning - action"
 on:
  push:
    branches: [master, ]
    paths-ignore:
    - 'site/**'
  pull_request:
    # The branches below must be a subset of the branches above
    branches: [master]
    paths-ignore:
    - 'site/**'
  schedule:
    - cron: '0 12 * * 2'
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,11 @@
 # How to contribute to ZITADEL
 ## **Did you find a bug?**
 ## **Did you find a security flaw?**
 * Please read [Security Policy](SECURITY.md).
 ## **Do you want to contribute to the ZITADEL documentation?**
 * Please read [Contributing to the ZITADEL Documentation](site/CONTRIBUTING.md).
--- a/README.md
+++ b/README.md
@ -1,4 +1,4 @@
-<img src="./docs/img/zitadel-logo-dark@2x.png" alt="Zitadel Logo" height="100px" width="auto" />
+<img src="./site/static/logos/zitadel-logo-dark@2x.png" alt="Zitadel Logo" height="100px" width="auto" />
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 [![Release](https://github.com/caos/zitadel/workflows/Release/badge.svg)](https://github.com/caos/zitadel/actions)
@ -7,48 +7,49 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/caos/zitadel)](https://goreportcard.com/report/github.com/caos/zitadel)
 [![codecov](https://codecov.io/gh/caos/zitadel/branch/master/graph/badge.svg)](https://codecov.io/gh/caos/zitadel)
-> This project is in a alpha state. The application will continue breaking until version 1.0.0 is released
+> This project is in a beta state and API might still change a bit
 ## What Is It
-`ZITADEL` is a Cloud Native Identity and Access Management solution. All server side components are written in `Go` and the management interface, called `Console`, is written in `Angular`.
+**ZITADEL** is a "Cloud Native Identity and Access Management" solution. All server side components are written in [**Go**](https://golang.org/) and the management interface, called **Console**, is written in [**Angular**](https://angular.io/).
-We optimized `ZITADEL` for the usage as `service provider IAM`. By `service provider` we think of companies who build services for e.g SaaS cases. Often these companies would like to use an IAM where they can register their application and grant other people or companies the right to self manage a set of roles within that application.
+We optimized **ZITADEL** for the usage as "service provider" IAM. By "service provider" we think of companies who build services for e.g SaaS cases. Often these companies would like to use an IAM where they can register their application and grant other people or companies the right to self manage a set of roles within that application.
 ## How Does It Work
-We built `ZITADEL` around the idea that the IAM should be easy to deploy and scale. That's why we tried to reduce external systems as much as possible.
+We built **ZITADEL** around the idea that the IAM should be easy to deploy and scale. That's why we tried to reduce external systems as much as possible.
-For example, `ZITADEL` is eventsourced but it does not rely on a pub/sub system to function. Instead we built all the functionality right into one binary.
+For example, **ZITADEL** is event sourced but it does not rely on a pub/sub system to function. Instead we built all the functionality right into one binary.
-`ZITADEL` only needs `Kubernetes` for orchestration and `CockroachDB` as storage.
+**ZITADEL** only needs [**Kubernetes**](https://kubernetes.io/) for orchestration and [**CockroachDB**](https://www.cockroachlabs.com/) as storage.
 ## Why Another IAM
-In the past we already built a closed sourced IAM and tested multiple others. With most of them we had some issues, either technology, feature, pricing or transparency related in nature. For example we find the idea that security related features like `MFA` should not be hidden behind a paywall or a feature price.
+In the past we already built a closed sourced IAM and tested multiple others. With most of them we had some issues, either technology, feature, pricing or transparency related in nature. For example we find the idea that security related features like **MFA** should not be hidden behind a paywall or a feature price.
-One feature that we often missed, was a solid `audit trail` of all IAM resources. Most systems we saw so far either rely on simple log files or use a short retention for this.
+One feature that we often missed, was a solid **audit trail** of all IAM resources. Most systems we saw so far either rely on simple log files or use a short retention for this.
 ## How To Use It
 ### Use our free tier
-Stay tuned, we will publish how you can register an organisation in our cloud offering `zitadel.ch` soon.
+We provide a shared-cloud ZITADEL system where people can register there own organisation.
-Yes we have a free tier!
+Until end of 2020 we operator under a **early access** model where everything is free.
 Go check it out under [zitadel.ch](https://zitadel.ch)
 ### Run your own IAM
-Stay tuned, we will soon publish a guide how you can deploy a `hyperconverged` system with our automation tooling called `ORBOS`.
+Stay tuned, we will soon publish a guide how you can deploy a **hyperconverged** system with our automation tooling called [**ORBOS**](https://github.com/caos/orbos/).
-With [ORBOS](https://github.com/caos/orbos/) you will be able to run `ZITADEL` on `GCE` or `StaticProvider` within 20 minutes. To achieve this, [ORBOS](https://github.com/caos/orbos/) will bootstrap and maintain a `Kubernetes` cluster, essential platform components (logging, metrics, ingress, ...), a secure `CockroachDB` cluster and `ZITADEL` itself.
+With [**ORBOS**](https://github.com/caos/orbos/) you will be able to run [**Kubernetes**](https://kubernetes.io/) on **GCE** or **StaticProvider** within 20 minutes. To achieve this, [[**ORBOS**](https://github.com/caos/orbos/) will bootstrap and maintain a [**Kubernetes**](https://kubernetes.io/) cluster, essential platform components (logging, metrics, ingress, ...), a secure [**CockroachDB**](https://www.cockroachlabs.com/) cluster and **ZITADEL** itself.
-The combination of the tools [ORBOS](https://github.com/caos/orbos/) and `ZITADEL` is what makes the operation easy and scalable.
+The combination of the tools [**ORBOS**](https://github.com/caos/orbos/) and **ZITADEL** is what makes the operation easy and scalable.
 See our progress [here](https://github.com/caos/orbos/pull/256)
 ## Give me some docs
-This is work in progess but will change soon.
+Have a look at our constantly evolving docs page [docs.zitadel.ch](https://docs.zitadel.ch).
 ## How To Contribute
-TBA
+Details need to be announced, but feel free to contribute already. As long as you are okay with accepting to contribute under this projects OSS [License](##License) you are fine.
 We already have documentation specific [guidelines](./site/CONTRIBUTING.md).
 ## Security
@ -59,3 +60,4 @@ See the policy [here](./SECURITY.md)
 See the exact licensing terms [here](./LICENSE)
 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
--- a/build/build.md
+++ b/build/build.md
@ -1,5 +0,0 @@
 # Build
 ## Console
 ## Docker
--- a/docs/local.md
+++ b/docs/local.md
@ -1,35 +0,0 @@
 ## local development
 ### start cockroach in docker
 ```bash
 docker rm -f zitadel-db &&
 rm -rf ${GOPATH}/src/github.com/caos/zitadel/cockroach-data &&
 docker run -d \
 --name=zitadel-db \
 --hostname=zitadel-db \
 -p 26257:26257 -p 8080:8080  \
 -v "${GOPATH}/src/github.com/caos/zitadel/cockroach-data/zitadel1:/cockroach/cockroach-data"  \
 cockroachdb/cockroach:latest start --insecure
 ``` 
 ### local database migrations
 #### local migrate
 `go generate $GOPATH/src/github.com/caos/zitadel/migrations/cockroach/migrate_local.go`
 #### local cleanup
 `go generate $GOPATH/src/github.com/caos/zitadel/migrations/cockroach/clean_local.go`
 ### Connect to Cockroach
 `docker exec -it "zitadel-db" /cockroach/cockroach sql --insecure`
 #### Should show eventstore, management, admin, auth
 `show databases;`
--- a/site/CONTRIBUTING.md
+++ b/site/CONTRIBUTING.md
@ -0,0 +1,69 @@
 # How to contribute to ZITADEL's documentation
 Before you start your editing process please take some time to familiarise yourself with the rules for contributing to the documentation of ZITADEL.
 ## File format
 ZITADEL's static site generator uses a Markdown file format. The flavour of the Markdown is specified in the [CAOS Static Site Generator](/docs/cssg.md) document.
 ## Using headings
 Make use of headings to structure and organise the document. The static site generator will make sure that the headings are rendered as a means of navigation for the site's content.
 ## Headings capitalisation conventions
 In order to keep consistency across the documentation we urge you to only write the very first word of a heading with a capital letter. The styling of the static site generator will then guarantee the consistent rendering of first caps, all caps, word caps or whatever style is chosen for the output.
 ## Using captions
 We urge you to always add captions to listings, code snippets, tables, graphics and images, *unless* the image is a logo or icon of any type. Also, inline graphics and images don't require captions due to readability.
 Numbering is **required** for captions. See next section.
 ## Numbering of captions
 Numbering has to be continuous using Arabic style numbers. The caption is composed of a prefix and a descriptive text. The prefix is composed of the item type (Listing, Table, Image, Graphic), an incrementing number in Arabic style followed by a period and a description.
 If the description consists of **one term** only you must omit any trailing punctuation. If the description represents a complete sentence you must terminate it with a period.
 Examples:
 * Snippet 3. Example of a protobuf interface deriving ZITADEL's OIDC connector.
 * Figure 1. Inside the ESO Atacama Large Millimetre/submillimetre Array.
 * Table 21. Representation of all supported quantum-singularity proximation algorithms.
 * Image 13. Higgs Boson
 ## Inline graphics and images
 Use sparsely. You should always make sure that inline images do not exceed 48 by 48 pixels (or the equivalent scale for HDPI displays).
 ## Keyboard shortcuts
 When documenting the usage of UI components don't forget to include the keyboard shortcuts available. Use the `kbd:` macro or `<kbd>` HTML tag to style the keys accordingly. To ensure platform-independent documentation always include the modifier-keys for **all** supported platforms, i.e. `[kbd:]Ctrl` or `[kbd:]Opt [kbd:]C`, which renders `<kbd>Ctrl</kbd>` or `<kbd>Opt</kbd> <kbd>C</kbd>`.
 ## File name conventions
 ### File name
 If and when the file name of a Markdown file consist of more than **one** contiguous word you must use a hyphen `-` to separate the word elements.
 Examples:
 * content.md
 * distribution-guide.md
 * programming-examples.md
 * explaining-the-code-snippets.md
 ### File extension
 For reasons of consistency the static site generator only accepts Markdown files with the `.md` file extension.
 ### Internationalisation (I18N)
 Writing documentation in country specific languages is highly endorsed. The static site generator makes use of a simple naming convention for Markdown files which are available in different languages:
 `{filename}[.{language-id}].md`
 Where `filename` represents the name of the file (see section [File name](#file-name)), `language-id` is an *optional* language identifier (see the list of [ISO 639-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)), and the mandatory file extension `.md`.
 **Note:** If a file name does not specify a language identifier we consider the file name to be implicitly written in English language (defaulting to `.en`). This is also important for the rendering of the language-dependent content navigation as the content navigations always will only include pages in their respective language they represent. This means that Markdown files without language identifier will **only** be rendered in the content navigation of the English documentation variant and will **not be visible at all** in the content navigations of other language variants.
--- a/site/README.md
+++ b/site/README.md
@ -1,7 +1,7 @@
-## Getting started
+# Getting started
-Caos Site is a github action that generates a static page out of markdown files. It uses marked.js in combination with highlight.js to compile and style markdown.
+CAOS Site is a github action that generates a static page out of markdown files. It uses marked.js in combination with highlight.js to compile and style markdown.
-The documentiation is built according to the structure of a docs `folder`[Folder](https://github.com/caos/site/tree/master/docs) located at root of the targeted repository.
+The documentation is built according to the structure of a docs `folder`[Folder](https://github.com/caos/site/tree/master/site/docs) located at root of the targeted repository.
 ## Running locally
--- a/site/docs/administrate/00-overview.de.md
+++ b/site/docs/administrate/00-overview.de.md
@ -0,0 +1,5 @@
 ---
 title: Übersicht
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/00-overview.en.md
+++ b/site/docs/administrate/00-overview.en.md
@ -0,0 +1,40 @@
 ---
 title: Overview
 ---
 > All documentations are under active work and subject to change soon!
 ### Features
 - Single-Sign On (SSO) and Single-Log Out (SLO) for
  - Web applications
    - Server Renderer
    - Single Page
  - Native Clients
    - Windows
    - MacOS
    - Linux
  - Mobile Clients
    - Android
    - iOS / iPadOS
 - Bearer Tokens to use with APIs
  - REST
  - GRPC
  - GraphQL
 - Role Based Access Control
 - OpenID Connect 1.0 (OIDC) support
 - OAuth 2.0 support
 - Identity Brokering
  - Federation with OIDC and OAuth 2.0 Identity Providers
  - Social Login
 - Management Console for central management of your data
 - Multi-factor Authentication
  - Support for TOTP/HOTP with any app, like authy, google authenticator, ...
 - User self-registration, recover password, email and phone verification, etc.
 - Organisation self-registration, domain verification, policy management
 - API's for easy integration in your application
 ### Concepts
 With ZITADEL there are some key concepts some should be aware of before using it to secure your applications and services.
 You find these definitions in the "What is..." heading of each resource.
--- a/site/docs/administrate/01-console.de.md
+++ b/site/docs/administrate/01-console.de.md
@ -0,0 +1,5 @@
 ---
 title: Console
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/01-console.en.md
+++ b/site/docs/administrate/01-console.en.md
@ -0,0 +1,30 @@
 ---
 title: Console
 ---
 ### What is Console
 Console is the ZITADEL Graphical User Interface.
 **Users** can manage some information by their own.
 - profile information
 - credentials
 - external logins
 Users (**org owners**) who manage organisations do this also with Console.
 - Organisation settings (policies, domains, idp's)
 - Manage users
 - Manage projects, clients and roles
 - Give access to users
 For the **IAM Administrators** there is also a section in Console solely intended to manage the system.
 - Check failed events
 - Reset read models
 - Define system policies
 ### Technologies
 Console is built with Angular and interfaces with ZITADEL by utilizing the GRPC APIs over GRPC-web.
--- a/site/docs/administrate/02-organisations.de.md
+++ b/site/docs/administrate/02-organisations.de.md
@ -0,0 +1,5 @@
 ---
 title: Organisationen
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/02-organisations.en.md
+++ b/site/docs/administrate/02-organisations.en.md
@ -0,0 +1,43 @@
 ---
 title: Organisations
 ---
 ### What are organisations
 Organisations are comparable to tenants of a system or OU's (organisational units) if we speak of a directory based system.
 ZITADEL is organised around the idea that multiple organisations share the same [System](administrate#What_is_meant_by_system) and that they can grant each other rights so self manage certain things.
 #### Global organisation
 ZITADEL provides a global organisation for users who manage their accounts on their own. Think of this like the difference between a "Microsoft Live Login" vs. "AzureAD User"
 or if you think of Google "Gmail" vs "Gsuite".
 ### Create an organisation without existing login
 ZITADEL allows you to create a new organisation without a pre-existing user. For [ZITADEL.ch](https://zitadel.ch) you can create a org by visiting the [Register organisation](https://accounts.zitadel.ch/register/org)
 > Screenshot here
 For dedicated ZITADEL instances this URL might be different, but in most cases should be something like https://accounts.YOURDOMAIN.TLD/register/org
 ### Create an organisation with existing login
 You can simply create a new organisation by visiting the [ZITADEL Console](https://console.zitadel.ch) and clicking "new organisation" in the upper left corner.
 > Screenshot here
 For dedicated ZITADEL instances this URL might be different, but in most cases should be something like `https://console.YOURDOMAIN.TLD`
 ### Verify a domain name
 Once you created your organisation you will receive a generated domain name from ZITADEL for your organisation. For example if you call your organisation `ACME` you will receive `acme.zitadel.ch` as name. Furthermore the users you create will be suffixed with this domain name. To improve the user experience you can verify a domain name which you control. If you control acme.ch you can verify the ownership by DNS or HTTP challenge.
 After the domain is verified your users can use both domain names to log-in. The user "coyote" can now use "coyote@acme.zitadel.ch" and "coyote@acme.ch".
 An organisation can have multiple domain names, but only one of it can be primary. The primary domain defines which login name ZITADEL displays to the user, and also what information gets asserted in access_tokens (preferred_username).
 > Screenshot here
 ### Audit organisation changes
 All changes to the organisation are displayed on the organisation menu within [ZITADEL Console](https://console.zitadel.ch/org) organisation menu. Located on the right hand side under "activity".
 > Screenshot here
--- a/site/docs/administrate/03-projects.de.md
+++ b/site/docs/administrate/03-projects.de.md
@ -0,0 +1,5 @@
 ---
 title: Projekte
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/03-projects.en.md
+++ b/site/docs/administrate/03-projects.en.md
@ -0,0 +1,58 @@
 ---
 title: Projects
 ---
 ### What are projects
 The idea of projects is to have a vessel for all components who are closely related to each other.
 In ZITADEL all clients located in the same project share their roles, grants and authorizations.
 From a access management perspective you manage who has what role in the project and your application consume this information.
 A project belongs to exactly one organisation.
 The attribute project role assertion defines, if the roles should be integrated in the tokens without sending corresponding scope (urn:zitadel:iam:org:project:role:{rolename})
 With the project role check you can define if a user should have a requested role to be able to logon.
 **Clients**
 Clients are described here [What are clients](administrate#What_are_clients)
 Basically these are you applications who initiate the authorization flow.
 **Roles**
 [Roles (or Project Roles)](administrate#Roles) is a mean of managing users access rights for a certain project.
 These [roles](administrate#Roles)  are opaque for ZITADEL and have no weight in relation to each other.
 So if a [user](administrate#Users) has two roles, admin and user in a certain project, the information will be treated additive.
 **Grants**
 With ZITADEL it is possible to give third parties (other organisations) the possibility to manage certain roles on their own.
 To achieve this the owner of a project can grant (some could say delegate) certain roles or all roles to a organisation.
 After granting that organisation it can manage on its own which user has what roles.
 This feature is especially useful for service providers, because they are able to establish a great self-service culture for their business customers.
 **Authorizations** 
 #### Project vs. granted Project
 The simple difference of a project vs a granted project is that a project belongs to your organisation and the granted project belongs to a third party who did grant you some rights to manage certain roles of their project.
 To make it more easily to differentiate ZITADEL Console displays these both as separate menu in the project section.
 ### Manage a project
 > Screenshot here
 #### RBAC Settings
 - Authorisation Check option (Check if the user at least has one role granted)
 - Enable Project_Role Assertion (if this is enabled assert project_roles, with the config of the corresponding client)
 #### Define project specific roles
 > Screenshot here
 ### Grant project to a third party
 > Screenshot here
 ### Audit project changes
 > Screenshot here
--- a/site/docs/administrate/04-clients.de.md
+++ b/site/docs/administrate/04-clients.de.md
@ -0,0 +1,5 @@
 ---
 title: Clients
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/04-clients.en.md
+++ b/site/docs/administrate/04-clients.en.md
@ -0,0 +1,22 @@
 ---
 title: Clients
 ---
 ### What are clients
 Clients are applications who share the same security context and interface with an "authorization server".
 For example you could have a software project existing out of a web app and a mobile app, both of these application might consume the same roles because the end user might use both of them.
 ### Manage clients
 Clients might use different protocols for integrating with an IAM. With ZITADEL it is possible to use OpenID Connect 1.0 / OAuth 2.0. In the future SAML 2.0 support is planned as well.
 > Screenshot here
 ### Configure OpenID Connect 1.0 Client
 To make configuration of a client easy we provide a wizard which generates a specification conferment setup.
 The wizard can be skipped for people who are needing special settings.
 For use cases where your configuration is not compliant we provide you a "dev mode" which disables conformance checks.
 > Screenshot here
--- a/site/docs/administrate/05-roles.de.md
+++ b/site/docs/administrate/05-roles.de.md
@ -0,0 +1,5 @@
 ---
 title: Rollen
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/05-roles.en.md
+++ b/site/docs/administrate/05-roles.en.md
@ -0,0 +1,41 @@
 ---
 title: Roles
 ---
 ### What are Roles
 With **roles** **ZITADEL** lets [projects](administrate#projects) define there **role based access controle**.
 **Roles** can be consumed by the [clients](administrate#clients) which exist witing a specific [project](administrate#projects).
 For more information about how **roles** can be consumed have a look the the protocol specific information.
 - [OpenID Connect / OAuth](integrate#How_to_consume_authorizations_in_your_application_or_service)
 ### Manage Roles
 Each **role** consist of three fields.
 | Field        | Description                                                                  | Example                                          |
 |:-------------|:-----------------------------------------------------------------------------|--------------------------------------------------|
 | Key          | This is the **Roles** actual name which can be used to verify the users roles.                                            | User                                             |
 | Display Name | A descriptive text for the purpose of the **Role**                           | User is the default role provided to each person |
 | Group        | The group field allows to group certain roles who belong in the same context | User and Admin in the group **default**          |
 ### Grantig Roles
 To give someone (or somewhat) access to a [projects](administrate#projects) resources and services **ZITADEL** provides to processes. **Roles** can be either granted to [users](administrate#Users) org to [organisations](administrate#Organisations).
 #### Grant Roles to Organisations
 The possibility to grant **roles** to an [organisation](administrate#Organisations) is intented as "delegation" so that a [org](administrate#Organisations) can on their own grant access to [users](administrate#Users).
 For example a **service provider** could grant the **roles** user, and manager to an [org](administrate#Organisations) as soon as they purchases his service. This can be automated by utilising a [service user](administrate#Manage_Service_Users) in the **service providers** business process.
 > Screenshot here
 #### Grant Roles to Users
 By granting **roles** to [users](administrate#Users), be it [humanes or machines](administrate#Human_vs_Service_Users), this [user](administrate#Users) recieves the authorization to access resources from a service.
 > Screenshot here
--- a/site/docs/administrate/06-users.de.md
+++ b/site/docs/administrate/06-users.de.md
@ -0,0 +1,5 @@
 ---
 title: Benutzer
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/06-users.en.md
+++ b/site/docs/administrate/06-users.en.md
@ -0,0 +1,48 @@
 ---
 title: Users
 ---
 ### What are users
 In ZITADEL there are different users. Some belong to dedicated organisations other belong to the global org. Some of them are human users others are machines.
 Nonetheless we treat them all the same in regard to roles management and audit trail.
 #### Human vs. Service Users
 The major difference between humane vs. machine users is the type of credentials who can be used.
 With machine users there is only a non interactive login process possible. As such we utilize “JWT as Authorization Grant”.
 > TODO Link to “JWT as Authorization Grant” explanation.
 ### How ZITADEL handles usernames
 ZITADEL is built around the concept of organisations. Each organisation has it's own pool of usernames which include human and service users.
 For example a user with the username `alice` can only exist once the org. `ACME`. ZITADEL will automatically generate a "logonname" for each user consisting of `{username}@{domainname}.{zitadeldomain}`. Without verifying the domain name this would result in the logonname `alice@acme.zitadel.ch`. If you use a dedicated ZITADEL replace `zitadel.ch` with your domain name.
 If someone verifies a domain name within the org. ZITADEL will generate additional logonames for each user with that domain. For example if the domain is `acme.ch` the resulting logonname would be `alice@acme.ch` and as well the generated one `alice@acme.zitadel.ch`.
 > Domain verification also removes the logonname from all users who might have used this combination in the global org.
 > Relating to example with `acme.ch` if a user in the global org, let's call him `bob` used `bob@acme.ch` this logonname will be replaced with `bob@randomvalue.tld`
 > ZITADEL notifies the user about this change
 ### Manage Users
 #### Create User
 > Screenshot here
 #### Set Password
 > Screenshot here
 ### Manage Service Users
 > Screenshot here
 ### Authorizations
 > Screenshot here
 ### Audit user changes
 > Screenshot here
--- a/site/docs/administrate/07-policies.de.md
+++ b/site/docs/administrate/07-policies.de.md
@ -0,0 +1,5 @@
 ---
 title: Richtlinien
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/07-policies.en.md
+++ b/site/docs/administrate/07-policies.en.md
@ -0,0 +1,50 @@
 ---
 title: Policies
 ---
 ### What are policies
 Polices are a means of enforcing certain behavior of ZITADEL.
 ZITADEL defines a default policy on the system level. However a org. owner can change these aspects within his own org.
 Below is a list of available policies
 ### Password complexity
 This policy enforces passwords of users within the org. to be compliant.
 - min length
 - has number
 - has symbol
 - has lower case
 - has upper case
 > Screenshot here
 ### IAM Access Preference
 This policy enforces, when set to true, that usernames are suffixed with the organisations domain.
 Under normal operation this policy is only false on the `global` org. so that users can choose there email as username.
 Only available for the `IAM Administrator`
 > Screenshot here
 ### Login Options
 With this policy it is possible to define what options a user sees in the login process.
 - Username Password allowed
 - Self Register allowed
 - External IDP allowed
 - List of allowed external IDPs
 > Screenshot here
 ### Audit policy changes
 > Screenshot here
 ### Upcoming Policies
 - Password age
 - Password failure count
--- a/site/docs/administrate/08-providers.de.md
+++ b/site/docs/administrate/08-providers.de.md
@ -0,0 +1,5 @@
 ---
 title: Identitäts Provider
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/08-providers.en.md
+++ b/site/docs/administrate/08-providers.en.md
@ -0,0 +1,72 @@
 ---
 title: Identity Providers
 ---
 ### What are Identity Providers
 Identity providers or in short idp's are external systems to which **ZITADEL** can create a **federation** or use their **directory service**.
 Normally federation uses protocols like [OpenID Connect 1.0](https://openid.net/connect/), [OAuth 2.0](https://oauth.net/2/) and [SAML 2.0](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
 Some examples include:
 #### Social Providers
 - Google Account
 - Microsoft Live Account
 - Apple ID
 - GitHub
 - GitLab
 - ...
 #### Enterprise Providers**
 - Azure AD Tenant
 - Gsuite hosted domain
 - ...
 ### Generic
 - ADFS
 - ADDS
 - Keycloak
 - LDAP
 ### What is Identity Brokering
 ZITADEL supports the usage as identity broker, by linking multiple external idp's into one user.
 With identity brokering the client which relies on ZITADEL does not need to care about the linking of identity.
 ### Manage Identity Providers
 > Screenshot here
 ### Federation Protocols
 Currently supported are the following protocols.
 - OpenID Connect 1.0
 - OAuth 2.0
 SAML 2.0 will follow later on.
 ### Storage Federation
 > This is a work in progress.
 Storage federation is a means of integrating existing identity storage like [LDAP](https://tools.ietf.org/html/rfc4511) and [ADDS](https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview).
 With this process **ZITADEL** can authenticate users with LDAP Binding and SPNNEGO for ADDS. It is also possible to synchronize the users just-in-time or scheduled.
 #### Sync Settings
 Here we will document all the different sync options
 - Readonly
 - Writeback
 - just-in-time sync
 - scheduled sync
 > TBD
 ### Audit identity provider changes
 > Screenshot here
--- a/site/docs/administrate/80-audit.de.md
+++ b/site/docs/administrate/80-audit.de.md
@ -0,0 +1,5 @@
 ---
 title: Audit
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/80-audit.en.md
+++ b/site/docs/administrate/80-audit.en.md
@ -0,0 +1,13 @@
 ---
 title: Audit
 ---
 ### What about Audit
 ZITADEL is built upon the concept of Event sourcing. With this ZITADEL can track each operation of all objects it maintains over an infinite amount of time. The only limit is the storage system.
 With these events ZITADEL can provide you with a super detailed audit trail where you can see who changed what and when.
 Over the next few releases we will steadily enhance and build features tailored to reporting and audit.
 > It is important to mention that even if ZITADEL does not yet supply the Graphical User Interface for certain audit aspects it still has all the data to generate these reports later on!
--- a/site/docs/administrate/90-system.de.md
+++ b/site/docs/administrate/90-system.de.md
@ -0,0 +1,5 @@
 ---
 title: System Administration
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/administrate/90-system.en.md
+++ b/site/docs/administrate/90-system.en.md
@ -0,0 +1,58 @@
 ---
 title: System Administration
 ---
 ### What is meant by system
 System describes the root of ZITADEL and includes all other elements like organisations, users and so on. Most of the time this part is managed by an user with the role IAM_OWNER.
 ### Default Policies
 When ZITADEL is setup for the first time we establish certain default polices for the whole system.
 > TODO Document default policy settings
 ### Manage Read Models
 Read Models are a way to normalize data out of the event stream for certain aspects. For example there is a model which consist of logonname and the password hash so that the login process can query that data.
 All read models are eventual consistent by nature and sometimes an administrator would like to verify they are still up-to date.
 In the ZITADEL Console is a section called administration available where the admin can check all read models and there current state.
 There is even a possibility to regenerate a read model.
 > When a read model is regenerated it might take up some time to be fully operational again
 > Depending on the model which is regenerated this might have a operational impact for the end-users
 > Screenshot here
 ### Secret Handling
 ZITADEL store secrets always encrypted or hashed in it's storage.
 Whenever feasible we try to utilize public / private key mechanics to handle secrets.
 **Encryption**
 We use `AES256` as default mechanic for storing secrets.
 **Password Hashing**
 By default `bcrypt` is used with a salt of `14`.
 > This mechanic is used for user passwords and client secrets
 **Signing Keys**
 These keys are randomly generated within ZITADEL and are rotated on a regular basis (e.g all 6h).
 > Signing keys are stored with AES256 encryption
 **TLS**
 Under normal operations ZITADEL's API nodes are located behind a reverse proxy. So the TLS Key handlings is out of context in this regard.
 However ZITADEL can use TLS keys at runtime level.
 > TODO Document TLS config
 ### IAM Configuration
 > TODO Document ZITADEL config
 ### Audit system changes
 > Screenshot here
--- a/site/docs/develop/00-overview.de.md
+++ b/site/docs/develop/00-overview.de.md
@ -0,0 +1,6 @@
 ---
 title: Übersicht
 description: …
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/develop/00-overview.en.md
+++ b/site/docs/develop/00-overview.en.md
@ -0,0 +1,36 @@
 ---
 title: Overview
 description: …
 ---
 > All documentations are under active work and subject to change soon!
 ### APIs
 ZITADEL provides three API's for different use cases. These API's are built with GRPC and then generate a REST service.
 Each services proto definition is located in the source control on GitHub.
 As we generate the REST services and Swagger file out of the proto definition we recommend that you rely on the proto file.
 We annotate the corresponding REST methods on each possible call as well as the AuthN and AuthZ requirements.
 See below for an example with the call **GetMyUser**.
 ```Go
  //User
  rpc GetMyUser(google.protobuf.Empty) returns (UserView) {
    option (google.api.http) = {
      get: "/users/me"
    };
    option (caos.zitadel.utils.v1.auth_option) = {
      permission: "authenticated"
    };
  }
 ```
 As you can see the `GetMyUser` function is also available as REST service under the path `/users/me`.
 In the table below you can see the URI of those calls.
 | Service | URI                                                                                                                                            |
 |:--------|:-----------------------------------------------------------------------------------------------------------------------------------------------|
 | REST    | [https://api.zitadel.ch/auth/v1/users/me](https://api.zitadel.ch/auth/v1/users/me)                                                             |
 | GRPC    | [https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/GetMyUser](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/GetMyUser) |
--- a/site/docs/develop/01-authentication.de.md
+++ b/site/docs/develop/01-authentication.de.md
@ -0,0 +1,6 @@
 ---
 title: Authentication API
 description: …
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/develop/01-authentication.en.md
+++ b/site/docs/develop/01-authentication.en.md
@ -0,0 +1,18 @@
 ---
 title: Authentication API
 description: …
 ---
 ### Authentication aka Auth
 The authentication API (aka Auth API) is used for all operations on the currently logged in user.
 | Service | URI                                                                                                                         |
 |:--------|:----------------------------------------------------------------------------------------------------------------------------|
 | REST    | [https://api.zitadel.ch/auth/v1/](https://api.zitadel.ch/auth/v1/)                                                          |
 | GRPC    | [https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService) |
 > At a later date we might expose functions to build your own login GUI
 > You can build your own user Register GUI already by utilizing the [Management API](#management)
 [Latest API Version](https://github.com/caos/zitadel/blob/master/pkg/grpc/auth/proto/auth.proto)
--- a/site/docs/develop/02-management.de.md
+++ b/site/docs/develop/02-management.de.md
@ -0,0 +1,6 @@
 ---
 title: Management API
 description: …
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/develop/02-management.en.md
+++ b/site/docs/develop/02-management.en.md
@ -0,0 +1,15 @@
 ---
 title: Management API
 description: …
 ---
 ### Management
 The management API is as the name states the interface where systems can mutate IAM objects like, organisations, projects, clients, user and so on if they have the necessary access rights.
 | Service | URI                                                                                                                                                 |
 |:--------|:----------------------------------------------------------------------------------------------------------------------------------------------------|
 | REST    | [https://api.zitadel.ch/management/v1/](https://api.zitadel.ch/management/v1/)                                                                      |
 | GRPC    | [https://api.zitadel.ch/caos.zitadel.management.api.v1.ManagementService/](https://api.zitadel.ch/caos.zitadel.management.api.v1.ManagementService) |
 [Latest API Version](https://github.com/caos/zitadel/blob/master/pkg/grpc/management/proto/management.proto)
--- a/site/docs/develop/03-administration.de.md
+++ b/site/docs/develop/03-administration.de.md
@ -0,0 +1,6 @@
 ---
 title: Admin API
 description: …
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/develop/03-administration.en.md
+++ b/site/docs/develop/03-administration.en.md
@ -0,0 +1,15 @@
 ---
 title: Admin API
 description: …
 ---
 ### Administration aka Admin
 This API is intended to configure and manage the IAM itself.
 | Service | URI                                                                                                                             |
 |:--------|:--------------------------------------------------------------------------------------------------------------------------------|
 | REST    | [https://api.zitadel.ch/admin/v1/](https://api.zitadel.ch/admin/v1/)                                                            |
 | GRPC    | [https://api.zitadel.ch/caos.zitadel.admin.api.v1.AdminService/](https://api.zitadel.ch/caos.zitadel.admin.api.v1.AdminService) |
 [Latest API Version](https://github.com/caos/zitadel/blob/master/pkg/grpc/admin/proto/admin.proto)
--- a/site/docs/documentation/00-introduction.de.md
+++ b/site/docs/documentation/00-introduction.de.md
@ -0,0 +1,3 @@
 ---
 title: Einführung
 ---
--- a/site/docs/documentation/00-introduction.en.md
+++ b/site/docs/documentation/00-introduction.en.md
@ -0,0 +1,13 @@
 ---
 title: Introduction
 description: This is the place for all things ZITADEL. Whether you are a developer, an integrator or a user of ZITADEL, then the following pages are written for your referral.
 ---
 > All documentations are under active work and subject to change soon!
 The documentation for ZITADEL comprises two major subject areas:
 1. Manuals for users, support organisations and administrators.
 2. Technical resources for developers and integrators.
 Please be reminded that ZITADEL is open source — and so is the documentation. Should you happen to stumble over an incorrectness, a spelling mistake, a hard-to-understand text passage, please don’t hesitate to leave a comment or propose a corresponding change.
--- a/site/docs/documentation/01-priciples.de.md
+++ b/site/docs/documentation/01-priciples.de.md
@ -0,0 +1,20 @@
 ---
 title: Prinzipien
 ---
 - Seien Sie bei Ihren Entscheidungen transparent
 - Zustandsloses Anwendungsdesign
 - Das System der Aufzeichnungen ist der Ereignisspeicher
 - Alles andere muss regeneriert werden können
 - Versuchen Sie nicht, komplexe Probleme außerhalb des IAM-Bereichs zu lösen
 - Verwenden Sie skalierbaren Speicher für den Ereignisspeicher und die Abfragemodelle
 - Versuchen Sie, wenn immer möglich idempotent zu sein
 - Reduzieren Sie die Notwendigkeit von System- oder externen Abhängigkeiten so weit wie möglich
 - Automatisierung einbeziehen
 - Zuerst die Design-API
 - Optimieren Sie alle Komponenten für den Betrieb am zweiten Tag
 - Verwenden Sie nur Open-Source-Projekte mit permissiven Lizenzen
 - Rollen Sie nicht Ihre eigene Krypto
 - Standard so weit wie möglich einbeziehen
 - Nutzen Sie die Funktionen der Plattform
 - Mit einem CDN und einer WAF laufen können
--- a/site/docs/documentation/01-priciples.en.md
+++ b/site/docs/documentation/01-priciples.en.md
@ -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 opensource 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 sematic versioning and release whenever feasible
--- a/site/docs/documentation/02-architecture.de.md
+++ b/site/docs/documentation/02-architecture.de.md
@ -0,0 +1,5 @@
 ---
 title: Architektur
 ---
 > TBD
--- a/site/docs/documentation/02-architecture.en.md
+++ b/site/docs/documentation/02-architecture.en.md
@ -0,0 +1,5 @@
 ---
 title: Architecture
 ---
 > TBD
--- a/site/docs/documentation/03-openidoauth.de.md
+++ b/site/docs/documentation/03-openidoauth.de.md
@ -0,0 +1,5 @@
 ---
 title: OpenID Connect 1.0 & OAuth 2.0
 ---
 > TBD
--- a/site/docs/documentation/03-openidoauth.en.md
+++ b/site/docs/documentation/03-openidoauth.en.md
@ -0,0 +1,142 @@
 ---
 title: OpenID Connect 1.0 & OAuth 2.0
 ---
 ### Endpoints and Domains
 This chapter documents the [OpenID Connect 1.0](https://openid.net/connect/) and [OAuth 2.0](https://oauth.net/2/) features provided by **ZITADEL**.
 Under normal circumstances **ZITADEL** need four domain names to operate properly.
 | Domain Name | Example             | Description                                                                                                                          |
 |:------------|:--------------------|--------------------------------------------------------------------------------------------------------------------------------------|
 | issuer      | issuer.zitadel.ch   | Provides the [OpenID Connect 1.0 Discovery Endpoint](#openid-connect-10-discovery)                                                   |
 | api         | api.zitadel.ch      | All ZITADEL API's are located under this domain see [API explanation](develop#APIs) for details                                      |
 | login       | accounts.zitadel.ch | The accounts.* page provides server renderer pages like login and register and as well the authorization_endpoint for OpenID Connect |
 | console     | console.zitadel.ch  | With the console.* domain we serve the assets for the management gui                                                                 |
 #### OpenID Connect 1.0 Discovery
 The OpenID Connect Discovery Endpoint is located with the issuer domain.
 For example with [zitadel.ch](zitadel.ch) this would be the domain [issuer.zitadel.ch](issuer.zitadel.ch). This would give us [https://issuer.zitadel.ch/.well-known/openid-configuration](https://issuer.zitadel.ch/.well-known/openid-configuration).
 **Link to spec.** [OpenID Connect Discovery 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-discovery-1_0.html)
 #### authorization_endpoint
 [https://accounts.zitadel.ch/oauth/v2/authorize](https://accounts.zitadel.ch/oauth/v2/authorize)
 > The authorization_endpoint is located with the login page, due to the need of accessing the same cookie domain
 #### token_endpoint
 [https://api.zitadel.ch/oauth/v2/token](https://api.zitadel.ch/oauth/v2/token)
 #### userinfo_endpoint
 [https://api.zitadel.ch/oauth/v2/userinfo](https://api.zitadel.ch/oauth/v2/userinfo)
 #### end_session_endpoint
 [https://accounts.zitadel.ch/oauth/v2/endsession](https://accounts.zitadel.ch/oauth/v2/endsession)
 > The end_session_endpoint is located with the login page, due to the need of accessing the same cookie domain
 #### jwks_uri
 [https://api.zitadel.ch/oauth/v2/keys](https://api.zitadel.ch/oauth/v2/keys)
 > Be aware that these keys can be rotated without any prior notice. We will however make sure that a proper `kid` is set with each key!
 #### OAuth 2.0 Metadata
 **ZITADEL** does not provide a OAuth 2.0 Metadata endpoint but instead provides a [OpenID Connect Discovery Endpoint](#openid-connect-10-discovery).
 ### Scopes
 #### How scopes work
 > TODO describe
 #### Reserved Scopes
 In addition to the standard compliant scopes we utilize the following scopes.
 | Scope                                           | Description                                                                                                                                                     | Example                                    |
 |:------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
 | urn:zitadel:iam:org:project:role:{rolename}     | By using this scope a [client](administrate#clients) can request the claim urn:zitadel:iam:roles:rolename} to be asserted when possible. As an alternative approach you can enable all [roles](administrate#Roles) to be asserted from the [project](administrate#projects) a [client](administrate#clients) belongs to. See details [here](administrate#RBAC_Settings)                                                  | urn:zitadel:iam:org:project:role:user      |
 | urn:zitadel:iam:org:domain:primary:{domainname} | When requesting this scope **ZITADEL** will enforce that the user is member of the selected organisation. If the organisation does not exist a failure is displayed | urn:zitadel:iam:org:domain:primary:acme.ch |
 | urn:zitadel:iam:role:{rolename}                 |                                                                                                                                                                 |                                            |
 ### Claims
 > TODO describe
 #### Reserved Claims
 | Claims                                          | Description | Example                                                                          |
 |:------------------------------------------------|:------------|----------------------------------------------------------------------------------|
 | urn:zitadel:iam:org:domain:primary:{domainname} |             | `{"urn:zitadel:iam:org:domain:primary": "acme.ch"}`                              |
 | urn:zitadel:iam:org:project:roles:{rolename}    |             | `{"urn:zitadel:iam:org:project:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }` |
 | urn:zitadel:iam:roles:{rolename}                |             |                                                                                  |
 ### Grant Types
 For a list of supported or unsupported `Grant Types` please have a look at the table below.
 | Grant Type                                            | Supported           |
 |:------------------------------------------------------|:--------------------|
 | Authorization Code                                    | yes                 |
 | Authorization Code with PKCE                          | yes                 |
 | Implicit                                              | yes                 |
 | Resource Owner Password Credentials                   | no                  |
 | Client Credentials                                    | yes                 |
 | Device Authorization                                  | under consideration |
 | Refresh Token                                         | work in progress    |
 | JSON Web Token (JWT) Profile                          | partially           |
 | Security Assertion Markup Language (SAML) 2.0 Profile | no                  |
 | Token Exchange                                        | work in progress    |
 #### Authorization Code
 **Link to spec.** [The OAuth 2.0 Authorization Framework Section 1.3.1](https://tools.ietf.org/html/rfc6749#section-1.3.1)
 #### Proof Key for Code Exchange
 **Link to spec.** [Proof Key for Code Exchange by OAuth Public Clients](https://tools.ietf.org/html/rfc7636)
 #### Implicit
 **Link to spec.** [The OAuth 2.0 Authorization Framework Section 1.3.2](https://tools.ietf.org/html/rfc6749#section-1.3.2)
 #### Client Credentials
 **Link to spec.** [The OAuth 2.0 Authorization Framework Section 1.3.4](https://tools.ietf.org/html/rfc6749#section-1.3.4)
 #### Refresh Token
 **Link to spec.** [The OAuth 2.0 Authorization Framework Section 1.5](https://tools.ietf.org/html/rfc6749#section-1.5)
 #### JSON Web Token (JWT) Profile
 **Link to spec.** [JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://tools.ietf.org/html/rfc7523)
 #### Token Exchange
 **Link to spec.** [OAuth 2.0 Token Exchange](https://tools.ietf.org/html/rfc8693)
 ### Device Authorization
 **Link to spec.** [OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/rfc8628)
 ### Not Supported Grant Types
 #### Resource Owner Password Credentials
 > Due to growing security concern we do not support this grant type. With OAuth 2.1 it looks like this grant will be removed.
 **Link to spec.** [OThe OAuth 2.0 Authorization Framework Section 1.3.3](https://tools.ietf.org/html/rfc6749#section-1.3.3)
 #### Security Assertion Markup Language (SAML) 2.0 Profile
 **Link to spec.** [Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://tools.ietf.org/html/rfc7522)
--- a/site/docs/get_started/00-introduction.de.md
+++ b/site/docs/get_started/00-introduction.de.md
@ -1,8 +0,0 @@
 ---
 title: Einführung
 ---
 ### Bevor es los geh't
 > Dies ist eine frühe Version unseres Dokumentgenerators. Es können noch einige Dinge ändern, bis wir Version 1.0 erreichen.
--- a/site/docs/get_started/00-introduction.en.md
+++ b/site/docs/get_started/00-introduction.en.md
@ -1,8 +0,0 @@
 ---
 title: Introduction
 ---
 ### Before we begin
 > This is an early version of our documentation. Some things may change until we hit version 1.0.
 > This Documentation is and always will be a WIP, and will therefore be updated frequently.
--- a/site/docs/get_started/01-capabilities.de.md
+++ b/site/docs/get_started/01-capabilities.de.md
@ -1,14 +0,0 @@
 ---
 title: Wie fange ich an?
 description: Dieses Dokument beschreibt die Schlüsselfähigkeiten und führt in verschiedene Startszenarien ein
 ---
 <!-- ## Wo fange ich mit der Zitadel-Authentifizierung an? -->
 ### I already have an authentication system
 Wenn Ihre App bereits über eine Anmeldeimplementierung verfügt und Sie diese zur Authentifizierung für Zitadel-Backend-Diensten verwenden möchten, lesen Sie unsere `Migrationsanleitung`.
 ### Ich möchte mein Authentifizierungssystem mit Zitadel erstellen 
 Wenn Sie eine neue App erstellen oder einer vorhandenen App eine Anmeldung hinzufügen, verfügt Zitadel über Bibliotheken und Dienste, mit denen Sie die sichere Authentifizierung implementieren können, ohne das Authentifizierungs-Backend selbst erstellen zu müssen. Die Zitadel-Authentifizierung ist eine vollständige Backend-Lösung, die die Anmeldung mit Kennwörtern und weiteren Faktoren zur verbesserten Sicherheit ermöglicht
--- a/site/docs/get_started/01-capabilities.en.md
+++ b/site/docs/get_started/01-capabilities.en.md
@ -1,14 +0,0 @@
 ---
 title: Where to start?
 description: This document explains zitadels key capabilities
 ---
 <!-- ## Where to start? -->
 ### I already have an authentication system
 If your app already has a sign-in implementation and you want to use it to authenticate with Zitadel backend services, read our `migration documentation`.
 ### I want to build my authentication system with Zitadel
 If you're building a new app or adding sign-in to an existing app, Zitadel has libraries and services that can help you implement secure authentication without having to build the authentication backend yourself. Zitadel Authentication is a complete backend solution for signing in with passwords and additional Factors for enhanced Security.
--- a/site/docs/get_started/02-go-structs.de.md
+++ b/site/docs/get_started/02-go-structs.de.md
@ -1,32 +0,0 @@
 ---
 title: Go structs
 ---
 ### Go structures
 You can reference go struct tables from our go struct generator.
 Provide a `doc_assets` folder with all generated files in it.
 Make sure that the `.md` file consists of no other than the table itself and metadata which defines name and description of the struct
 | Attribute                   | Description                                                                     | Default | Collection  |
 | --------------------------- | ------------------------------------------------------------------------------- | ------- | ----------  |
 | boomVersion                 | Version of BOOM which should be reconciled                                      |         |             |
 | forceApply                  | Relative folder path where the currentstate is written to                       |         |             |
 | currentStatePath            | Flag if --force should be used by apply of resources                            |         |             |
 | preApply                    | Spec for the yaml-files applied before applications   |         |             |
 | postApply                   | Spec for the yaml-files applied after applicatio      |         |             |
 | prometheus-operator         | Spec for the Prometheus-Operator ,               |         |             |
 | logging-operator            | Spec for the Banzaicloud Logging-Operator ,         |         |             |
 | prometheus-node-exporter    | Spec for the Prometheus-Node-Exporter ,        |         |             |
 | prometheus-systemd-exporter | Spec for the Prometheus-Systemd-Exporter , |         |             |
 | grafana                     | Spec for the Grafana , [                          |         |             |
 | ambassador                  | Spec for the Ambassador ,                                |         |             |
 | kube-state-metrics          | Spec for the Kube-State-Metrics ,                 |         |             |
 | argocd                      | Spec for the Argo-CD ,                              |         |             |
 | prometheus                  | Spec for the Prometheus instance ,                    |         |             |
 | loki                        | Spec for the Loki instance ,             |         |             |
 #### References
 To reference a table ...
--- a/site/docs/get_started/02-go-structs.en.md
+++ b/site/docs/get_started/02-go-structs.en.md
@ -1,32 +0,0 @@
 ---
 title: Go structs
 ---
 ### Go structures
 You can reference go struct tables from our go struct generator.
 Provide a `doc_assets` folder with all generated files in it.
 Make sure that the `.md` file consists of no other than the table itself and metadata which defines name and description of the struct
 | Attribute                   | Description                                                                     | Default | Collection  |
 | --------------------------- | ------------------------------------------------------------------------------- | ------- | ----------  |
 | boomVersion                 | Version of BOOM which should be reconciled                                      |         |             |
 | forceApply                  | Relative folder path where the currentstate is written to                       |         |             |
 | currentStatePath            | Flag if --force should be used by apply of resources                            |         |             |
 | preApply                    | Spec for the yaml-files applied before applications   |         |             |
 | postApply                   | Spec for the yaml-files applied after applicatio      |         |             |
 | prometheus-operator         | Spec for the Prometheus-Operator ,               |         |             |
 | logging-operator            | Spec for the Banzaicloud Logging-Operator ,         |         |             |
 | prometheus-node-exporter    | Spec for the Prometheus-Node-Exporter ,        |         |             |
 | prometheus-systemd-exporter | Spec for the Prometheus-Systemd-Exporter , |         |             |
 | grafana                     | Spec for the Grafana , [                          |         |             |
 | ambassador                  | Spec for the Ambassador ,                                |         |             |
 | kube-state-metrics          | Spec for the Kube-State-Metrics ,                 |         |             |
 | argocd                      | Spec for the Argo-CD ,                              |         |             |
 | prometheus                  | Spec for the Prometheus instance ,                    |         |             |
 | loki                        | Spec for the Loki instance ,             |         |             |
 #### References
 To reference a table ...
--- a/site/docs/get_started/03-concluding.de.md
+++ b/site/docs/get_started/03-concluding.de.md
@ -1,5 +0,0 @@
 ---
 title: Abschliessendes
 ---
 Das war unsere Dokumentation
--- a/site/docs/get_started/03-concluding.en.md
+++ b/site/docs/get_started/03-concluding.en.md
@ -1,5 +0,0 @@
 ---
 title: Concluding
 ---
 This was our documentation
--- a/site/docs/get_started/seo.json
+++ b/site/docs/get_started/seo.json
@ -1,16 +0,0 @@
 {
    "tags": [
        {
            "name": "twitter:title",
            "content":"Docs demo page"
        },
        {
            "name": "twitter:description",
            "content":"Docs demo page description"
        },
        {
            "name": "Description",
            "content":"Docs demo page description"
        }
    ]
 }
--- a/site/docs/integrate/00-overview.de.md
+++ b/site/docs/integrate/00-overview.de.md
@ -0,0 +1,6 @@
 ---
 title: Übersicht
 description: ...
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/integrate/00-overview.en.md
+++ b/site/docs/integrate/00-overview.en.md
@ -0,0 +1,10 @@
 ---
 title: Overview
 description: ...
 ---
 > All documentations are under active work and subject to change soon!
 ### Application Integration
 ### Service Integration
--- a/site/docs/integrate/01-openidoauth.de.md
+++ b/site/docs/integrate/01-openidoauth.de.md
@ -0,0 +1,6 @@
 ---
 title: OpenID Connect & OAuth
 description: ...
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/integrate/01-openidoauth.en.md
+++ b/site/docs/integrate/01-openidoauth.en.md
@ -0,0 +1,42 @@
 ---
 title:  OpenID Connect & OAuth
 description: ...
 ---
 ### Client Types / Profiles
 #### Single Page Application
 If your [client](administrate#Clients) is a single page application (SPA) we recommend that you use [Authorization Code](documentation#Authorization_Code) in combination with [Proof Key for Code Exchange](documentation#Proof_Key_for_Code_Exchange).
 This flow has great support with most modern languages and frameworks and is the recommended default.
 > In the OIDC and OAuth world this **client profile** is called "user-agent-based application"
 #### Server Side Application
 In the OIDC and OAuth world this client profile is called "web application"
 #### Mobile App / Native App
 In the OIDC and OAuth world this client profile is called "native application"
 ### How to consume authorizations in your application or service
 With ZITADEL you can manage the [roles](administrate#Roles) a [project](administrate#Projects) supplies to your users in the form of authorizations.
 On the [project](administrate#Projects) it can be configured how **project roles** are supplied to the [clients](administrate#Clients).
 By default ZITADEL asserts the claim **urn:zitadel:iam:org:project:roles** to the [Userinfo Endpoint](documentation#userinfo_endpoint)
 - Assert the claim **urn:zitadel:iam:org:project:roles** to **access_token**
 - Assert the claim **urn:zitadel:iam:org:project:roles** to **id_token**
 ```JSON
 "urn:zitadel:iam:org:project:roles": {
    "user": {
      "id1": "acme.zitadel.ch",
      "id2": "caos.ch",
    }
  }
 ```
 For more details about how **ZITADEL** treats [scopes](documentation#Scopes) and [claims](documentation#Claims) see the [documentations](documentation).
--- a/site/docs/start/00-quick-start.de.md
+++ b/site/docs/start/00-quick-start.de.md
@ -0,0 +1,6 @@
 ---
 title: Schnellstart
 description: ...
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/start/00-quick-start.en.md
+++ b/site/docs/start/00-quick-start.en.md
@ -0,0 +1,29 @@
 ---
 title: Quick-Start
 description: A quick-start reference for the impatient reader.
 ---
 > All documentations are under active work and subject to change soon!
 ### Try ZITADEL
 You can either use [ZITADEL.ch](https://zitadel.ch) or deploy a dedicated ZITADEL instance.
 ### Use ZITADEL.ch
 To register your free organisation, visit this link [register organisation](https://accounts.zitadel.ch/register/org).
 After accepting the TOS and filling out all the required fields you will receive a mail with further instructions.
 #### Verify your domain name (optional)
 #### Add Users to your organisation
 #### Setup an application
 ### Use ORBOS to install ZITADEL
 > This will be added later on
 ### Install ZITADEL with static manifest
 > This will be added later on
--- a/site/docs/use/00-user.de.md
+++ b/site/docs/use/00-user.de.md
@ -0,0 +1,5 @@
 ---
 title: Benutzerhandbuch
 ---
 > This Language is not yet translated. Please consult the English version.
--- a/site/docs/use/00-user.en.md
+++ b/site/docs/use/00-user.en.md
@ -0,0 +1,21 @@
 ---
 title: User Manual
 ---
 > All documentations are under active work and subject to change soon!
 ### Self Register User
 ### Verify EMail
 ### Verify Phone
 ### Change Password
 ### Manage Multi Factor
 ### Federation
 #### Auto Register
 #### Manage Account Linking
--- a/site/src/components/Docs.svelte
+++ b/site/src/components/Docs.svelte
@ -4,8 +4,8 @@
  import Icon from "./Icon.svelte";
  import manifest from '../../static/manifest.json';
  export let owner = "caos";
-  export let project = "zitadel/site";
+  export let project = "zitadel";
-  export let path = "/docs";
+  export let path = "site/docs";
  export let dir = "";
  export let edit_title = "edit this section";
  export let sections;
@ -201,7 +201,7 @@
  }
  .content h2 {
-    margin-top: 8rem;
+    margin-top: 4rem;
    padding: 2rem 1.6rem 4rem 0.2rem;
    border-top: var(--border-w) solid #6767785b; /* based on --second */
    color: var(--text);
@ -265,8 +265,8 @@
  .content :global(h3),
  .content :global(h3 > code) {
-    margin: 6.4rem 0 0 0;
+    margin: 2.0rem 0 0 0;
-    padding: 2rem 1.6rem 5.6rem 0.2rem;
+    padding: 2rem 1.6rem 2.0rem 0.2rem;
    color: var(--text);
    border-top: var(--border-w) solid #6767781f; /* based on --second */
    background: transparent;
@ -292,7 +292,7 @@
    font-weight: 500;
    font-size: 2.4rem;
    color: var(--text);
-    margin: 6.4rem 0 1.6rem 0;
+    margin: 2.0rem 0 1.6rem 0;
    padding-left: 0;
    background: transparent;
    line-height: 1;
--- a/site/src/messages/de.json
+++ b/site/src/messages/de.json
@ -1,8 +1,16 @@
 {
-    "title": "Zitadel Identity and Access Management",
+    "title": "ZITADEL Identity and Access Management",
-    "description":"Die meisten Apps müssen die Identität eines Benutzers kennen. Wenn Sie die Identität eines Benutzers kennen, kann eine App Benutzerdaten sicher speichern und auf allen Geräten des Benutzers dieselbe personalisierte Erfahrung bieten.",
+    "description":"Die meisten Applikationen müssen die Identität eines Benutzers kennen, um Benutzerdaten sicher zu speichern und auf allen Geräten des Benutzers dieselbe personalisierte Erfahrung zu bieten.",
-    "description2":"Die Zitadel-Authentifizierung bietet Backend-Dienste, benutzerfreundliche SDKs und vorgefertigte UI-Bibliotheken zur Authentifizierung von Benutzern bei Ihrer App. Es unterstützt die Authentifizierung mithilfe von Passwörtern und bietet weitere Sicherheitsmechanismen, wie einen zweiten Faktor über OTP um einen sicheren Zugang zu gewährleisten.",
+    "description2":"Die Authentifizierung von ZITADEL bietet Backend-Dienste, benutzerfreundliche SDKs und vorgefertigte UI-Bibliotheken zur Authentifizierung von Benutzern in Ihrer Applikation. Es unterstützt die Authentifizierung mithilfe von Passwörtern und bietet weitere Sicherheitsmechanismen, wie einen zweiten Faktor beispielsweise über OTP, um einen sicheren Zugang zu gewährleisten.",
-    "description3":"Zitadel nutzt Industriestandards wie OAuth 2.0 und OpenID Connect, sodass sie problemlos in Ihr benutzerdefiniertes Backend integriert werden kann.",
+    "description3":"ZITADEL nutzt Industriestandards wie OAuth 2.0 und OpenID Connect, die leicht in Ihr benutzerdefiniertes Backend integriert werden können.",
-    "button":"Erfahren Sie wie sie starten",
+    "startlink": "Erfahren Sie hier, wie Sie starten",
-    "toconsole":"Zur Zitadel Konsole"
+    "integratelink": "Sichern Sie Ihre Applikationen und Schnittstellen",
    "administratelink": "Administrieren",
    "developlink":"Entwickeln",
    "docslink":"Dokumentation",
    "uselink":"Benutzer Handbuch",
    "toconsole":"ZITADEL Console öffnen"
 }
--- a/site/src/messages/en.json
+++ b/site/src/messages/en.json
@ -1,8 +1,15 @@
 {
-    "title": "Zitadel Identity and Access Management",
+    "title": "ZITADEL Identity and Access Management",
-    "description":"Most apps need to know the identity of a user. Knowing a user's identity allows an app to securely save user data in the cloud and provide the same personalized experience across all of the user's devices.",
+    "description":"Most applications need to know the identity of a user allowing to securely store user data in the cloud and provide the same personalised experience across all of the user's devices.",
-    "description2":"Zitadel Authentication provides backend services, easy-to-use SDKs, and ready-made UI libraries to authenticate users to your app. It supports authentication using passwords and uses additional Security, like a second Factor over OTP ensure a safe access.",
+    "description2":"ZITADEL's authentication provides backend services, easy-to-use SDKs, and ready-made UI libraries to authenticate users in your applicqtion. It supports authentication using passwords and applies additional security wirh the help of a second factor, for example OTP, to ensure a safe and secure access.",
-    "description3":"Zitadel Authentication leverages industry standards like OAuth 2.0 and OpenID Connect, so it can be easily integrated with your custom backend.",
+    "description3":"ZITADEL's authentication leverages industry standards like OAuth 2.0 and OpenID Connect so that it can be easily integrated in your custom backend.",
-    "button":"Learn how to get started",
+    "startlink": "Start using ZITADEL",
-    "toconsole":"Go to zitadel console"
+    "integratelink": "Secure your applications and apis with ZITADEL",
    "administratelink": "Administrate ZITADEL",
    "developlink":"Develop with the ZITADEL api's",
    "docslink":"ZITADEL Documentations",
    "uselink":"User Manuals",
    "toconsole":"Open ZITADEL Console"
 }
--- a/site/src/routes/index.svelte
+++ b/site/src/routes/index.svelte
@ -39,7 +39,7 @@
 <svelte:head>
  <title>
-    Caos • Documentation
+    ZITADEL • Documentation
  </title>
 </svelte:head>
@ -52,6 +52,14 @@
            <p>{$_('description2')}</p>
            <p>{$_('description3')}</p>
-            <a href="/get_started" >{$_('button')}</a>
+            <ul style="list-style-type: none;">
            <li><a href="/start" >{$_('startlink')}</a></li>
            <li><a href="/integrate" >{$_('integratelink')}</a></li>
            <li><a href="/administrate" >{$_('administratelink')}</a></li>
            <li><a href="/develop" >{$_('developlink')}</a></li>
            <li><a href="/documentation" >{$_('docslink')}</a></li>
            <li><a href="/use" >{$_('uselink')}</a></li>
            </ul>
        </div>
    </Section>
--- a/site/static/logos/zitadel-logo-dark@2x.png
+++ b/site/static/logos/zitadel-logo-dark@2x.png
--- a/site/static/manifest.json
+++ b/site/static/manifest.json
@ -1,9 +1,9 @@
 {
 	"background_color": "#212224",
 	"theme_color": "#e91e63",
-    "name": "Zitadel Docs",
+    "name": "ZITADEL Documentation",
    "lang": "en",
-	"short_name": "Zitadel Docs",
+	"short_name": "ZITADEL Docs",
 	"display": "minimal-ui",
 	"start_url": "/",
 	"icons": [