docs: proposal restructure (#5318)

* docs: docs structure * docs: remove sdk from main nav * docs: fix broken links * docs: texts * docs: texts * docs: react example * docs: proposal restructure * remove manual, move troubleshooting * revmove duplicate item * identity providers * broken links and rel paths * examples wip * examples * navigation * support * solution scenarios * concepts * overview * Actions caution to info * suggestions from code review * remove start command again * proposed start command (with and without api) * wip startpage * startpage * broken link integrate * remove get started from nav * Apply suggestions from code review Co-authored-by: Elio Bischof <[email protected]> --------- Co-authored-by: Fabienne <[email protected]> Co-authored-by: Florian Forster <[email protected]> Co-authored-by: Elio Bischof <[email protected]>
2026-11-13 17:35:12 +00:00 · 2023-03-07 09:33:13 +02:00
parent 23c14d9bd1
commit 8d4d182c20
61 changed files with 943 additions and 780 deletions
@@ -15,7 +15,7 @@ ZITADEL Managers are Users who have permission to manage ZITADEL itself. There a
 - **Project Mangers**: In this level the user is able to manage a project.
 - **Project Grant Manager**: The project grant manager is for projects, which are granted of another organization.

-On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../../guides/manage/console/managers#roles)
+On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](/guides/manage/console/managers#roles)

 ## Add ORG_OWNER to Service User

@@ -38,7 +38,7 @@ This is already described in the [Service User](serviceusers.md), so make sure y
 With the encoded JWT from the prior step, you will need to craft a POST request to ZITADEL's token endpoint:

 To access the ZITADEL APIs you need the ZITADEL Project ID in the audience of your token.
-This is possible by sending a custom scope for the audience. More about [Custom Scopes](../../apis/openidoauth/scopes)
+This is possible by sending a custom scope for the audience. More about [Custom Scopes](/apis/openidoauth/scopes)

 Use the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to include the ZITADEL project id in your audience

@@ -52,7 +52,7 @@ curl --request POST \
 ```

 - `grant_type` must be set to `urn:ietf:params:oauth:grant-type:jwt-bearer`
- `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
+- `scope` should contain any [Scopes](/apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
 - `assertion` is the encoded value of the JWT that was signed with your private key from the prior step

 You should receive a successful response with `access_token`, `token_type` and time to expiry in seconds as `expires_in`.
@@ -68,7 +68,7 @@ Content-Type: application/json
 }
 ```

-With this token you are allowed to access the [ZITADEL APIs](../../apis/introduction) .
+With this token you are allowed to access the [ZITADEL APIs](/apis/introduction) .

 ## Summary

@@ -78,4 +78,4 @@ With this token you are allowed to access the [ZITADEL APIs](../../apis/introduc

 Where to go from here:

- [ZITADEL API Documentation](../../apis/introduction)
+- [ZITADEL API Documentation](/apis/introduction)
@@ -145,7 +145,7 @@ You should get a successful response with a `totalResult` number of 1 and the de
 }
 ```

-With this token you are allowed to access the whole [ZITADEL System API](../../apis/system).
+With this token you are allowed to access the whole [ZITADEL System API](/apis/system).

 ## Summary

@@ -155,4 +155,4 @@ With this token you are allowed to access the whole [ZITADEL System API](../../a

 Where to go from here:

-* [ZITADEL API Documentation](../../apis/introduction)
+* [ZITADEL API Documentation](/apis/introduction)
@@ -12,7 +12,7 @@ You will need to provide some information about your app. We recommend creating
 1. Navigate to your Project
 2. Add a new application at the top of the page.
 3. Select Web application type and continue.
-4. Use [Authorization Code](../../apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange (PKCE)](../../apis/openidoauth/grant-types#proof-key-for-code-exchange).
+4. Use [Authorization Code](/apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange).
 5. Skip the redirect settings and confirm the app creation
 6. Copy the client ID, you will need to tell MongoDB Charts about it.
 7. When you created the app, expand its _OIDC Configuration_ section, change the _Auth Token Type_ to _JWT_ and save the change.
@@ -39,7 +39,7 @@ Your configuration should look similar to this:

 Embed a chart into your application now, following the corresponding [MongoDB docs](https://docs.mongodb.com/charts/saas/embed-chart-jwt-auth/).

-If you've done the [Angular Quickstart](../../examples/login/angular.md), your code could look something like this:
+If you've done the [Angular Quickstart](/examples/login/angular.md), your code could look something like this:

 ```html
 <!-- chart.component.html -->
@@ -29,7 +29,7 @@ To be able to access the ZITADEL APIs your service user needs permissions to ZIT
 1. Go to the detail page of your organization
 2. Click in the top right corner the "+" button
 3. Search for your service user
-4. Give the user the role you need, for the example we choose Org Owner (More about [ZITADEL Permissions](../manage/console/managers))
+4. Give the user the role you need, for the example we choose Org Owner (More about [ZITADEL Permissions](/guides/manage/console/managers))

 ![Add org owner to service user](/img/guides/console-service-user-org-owner.gif)

@@ -49,7 +49,7 @@ curl --request POST \
 ```

 * `grant_type` should be set to `client_credentials`
-* `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile`, `email`
+* `scope` should contain any [Scopes](/apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile`, `email`
  and `urn:zitadel:iam:org:project:id:zitadel:aud`. The latter provides access to the ZITADEL API.

 You should receive a successful response with `access_token`,  `token_type` and time to expiry in seconds as `expires_in`.
@@ -11,7 +11,7 @@ You need to give a user the [manager role](https://zitadel.com/docs/guides/manag
 If you like to know more about eventsourcing/eventstore and how this works in ZITADEL, head over to our [concepts](../../concepts/eventstore/overview).
 ## Request Events

-Call the [ListEvents](../../apis/admin) enpoint in the Administration API to get all the events you need.
+Call the [ListEvents](/apis/admin) enpoint in the Administration API to get all the events you need.
 To further restrict your result you can add the following filters:
 - sequence
 - editor user id
@@ -29,7 +29,7 @@ curl --request POST \

 ## Get event types

-To be able to filter for the different event types ZITADEL knows, you can request the [EventTypesList](../../apis/admin)
+To be able to filter for the different event types ZITADEL knows, you can request the [EventTypesList](/apis/admin)

 ```bash
 curl --request POST \
@@ -65,7 +65,7 @@ The following example shows you the event types for a password check (failed/suc

 ## Get aggregate types

-To be able to filter for the different aggregate types (resources) ZITADEL knows, you can request the [AggregateTypesList](../../apis/admin)
+To be able to filter for the different aggregate types (resources) ZITADEL knows, you can request the [AggregateTypesList](/apis/admin)

 ```bash
 curl --request POST \
@@ -1,5 +1,6 @@
 ---
-title: Connect with AzureAD through OIDC
+title: Configure AzureAD as Identity Provider
+sidebar_label: AzureAD
 ---

 ## AzureAD Tenant as Identity Provider for ZITADEL
@@ -87,7 +88,7 @@ If you don't want your users to get this prompt when using Azure, you have to di
 1. Go to the login behaviour settings of your instance or organization, depending if you like to disable it for all or just a specific organization respectively
 2. Set "Multi-factor init lifetimes" to 0

-![img.png](../../../static/img/guides/login_lifetimes.png)
+![img.png](/img/guides/login_lifetimes.png)

 #### Create user with verified email

@@ -104,11 +105,11 @@ To create the user with a verified email address you must add an action.
 https://github.com/zitadel/actions/blob/main/examples/verify_email.js
 ```

-![img.png](../../../static/img/guides/action_email_verify.png)
+![img.png](/img/guides/action_email_verify.png)

 3. Add the action "email verify" to the flow "external authentication" and to the trigger "pre creation"

-![img.png](../../../static/img/guides/action_pre_creation_email_verify.png)
+![img.png](/img/guides/action_pre_creation_email_verify.png)

 #### Automatically redirect to Azure AD

@@ -117,7 +118,7 @@ If you like to get automatically redirected to your Azure AD login instead of sh
 1. Go to the login behaviour settings of your instance or organization
 2. Disable login with username and password
 3. Make sure you have only configured AzureAD as external identity provider
-4. If you did all your settings on the organization level make sure to send the organization scope in your authorization request: [scope](../../apis/openidoauth/scopes#reserved-scopes)
+4. If you did all your settings on the organization level make sure to send the organization scope in your authorization request: [scope](/apis/openidoauth/scopes#reserved-scopes)

 ### Test the setup

@@ -1,22 +1,8 @@
 ---
-title: Identity Brokering
+title: Configure Google as Identity Provider
+sidebar_label: Google
 ---

-## What is Identity Brokering and 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 as identity federation.
-
-A service provider that specializes in brokering access control between multiple service providers (also referred to as relying parties) is called identity broker.
-Federated identity management is an arrangement that is made between two or more such identity brokers across organizations.
-
-Example:
-If Google is configured as identity provider on your organization, the user will get the option to use his Google Account on the Login Screen of ZITADEL (1).
-ZITADEL will redirect the user to the login screen of Google where he as to authenticated himself (2) and is sent back after he has finished that (3).
-Because Google is registered as trusted identity provider the user will be able to login in with the Google account after he linked an existing ZITADEL Account or just registered a new one with the claims provided by Google (4)(5).
-
-![Identity Brokering](/img/guides/identity_brokering.png)
-
 ## Register an external identity provider

 In this step we will add a new Google identity provider to federate identities with ZITADEL.
@@ -68,17 +54,17 @@ This case describes how to change it on the organization.

 ### 4. Send the primary domain scope on the authorization request

-ZITADEL will show a set of identity providers by default. This configuration can be changed by users with the [manager role](../../guides/manage/console/managers#roles) `IAM_OWNER`.
+ZITADEL will show a set of identity providers by default. This configuration can be changed by users with the [manager role](/guides/manage/console/managers#roles) `IAM_OWNER`.

 An organization's login settings will be shown

 - as soon as the user has entered the loginname and ZITADEL can identify to which organization he belongs; or
 - by sending a primary domain scope.
-  To get your own configuration you will have to send the [primary domain scope](../../apis/openidoauth/scopes#reserved-scopes) in your [authorization request](../../guides/integrate/login-users#auth-request) .
+  To get your own configuration you will have to send the [primary domain scope](/apis/openidoauth/scopes#reserved-scopes) in your [authorization request](/guides/integrate/login-users#auth-request) .
  The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login, also your branding and policies will trigger.

 :::note
-You need to create your own auth request with your applications parameters. Please see the docs to construct an [Auth Request](../../guides/integrate/login-users#auth-request).
+You need to create your own auth request with your applications parameters. Please see the docs to construct an [Auth Request](/guides/integrate/login-users#auth-request).
 :::

 Your user will now be able to choose Google for login instead of username/password or mfa.
@@ -0,0 +1,24 @@
+---
+title: Identity Brokering
+---
+
+## What is Identity Brokering and 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 as identity federation.
+
+A service provider that specializes in brokering access control between multiple service providers (also referred to as relying parties) is called identity broker.
+Federated identity management is an arrangement that is made between two or more such identity brokers across organizations.
+
+Example:
+If Google is configured as identity provider on your organization, the user will get the option to use his Google Account on the Login Screen of ZITADEL (1).
+ZITADEL will redirect the user to the login screen of Google where he as to authenticated himself (2) and is sent back after he has finished that (3).
+Because Google is registered as trusted identity provider the user will be able to login in with the Google account after he linked an existing ZITADEL Account or just registered a new one with the claims provided by Google (4)(5).
+
+![Identity Brokering](/img/guides/identity_brokering.png)
+
+## How to use external identity providers in ZITADEL
+
+Configure external identity providers on instance level or just for one organization via [Console](/guides/manage/console/instance-settings#identity-providers) or APIs.
+The guides in this will help you to set up specific identity providers.
+ZITADEL provides also templates to configure generic identity providers, which don't have a template.
@@ -58,7 +58,7 @@ So what do we want to achieve with delegated authentication?

 - Instead of sending around the user’s credentials
  - Clients may access protected resources with an **access token** that is only valid for specific scope and limited lifetime (OAuth 2.x)
-  - Users have to **authorize** applications to access certain [**scopes**](../../apis/openidoauth/scopes) (eg, email address or custom roles). Applications can request [**claims**](../../apis/openidoauth/claims) (key:value pairs, eg email address) for the authorized scopes with the access token or ID token from ZITADEL
+  - Users have to **authorize** applications to access certain [**scopes**](/apis/openidoauth/scopes) (eg, email address or custom roles). Applications can request [**claims**](/apis/openidoauth/claims) (key:value pairs, eg email address) for the authorized scopes with the access token or ID token from ZITADEL
  - Access tokens are bearer tokens, meaning that possession of the token provides access to a resource. But the tokens expire frequently and the application must request a new access token via **refresh token** or the user must reauthenticate

 ![Overview federated identities](/img/guides/consulting_federated_identities_basics.png)
@@ -119,7 +119,7 @@ _So what about APIs?_

 We recommend using **“JWT bearer token with private key”** ([RFC7523](https://tools.ietf.org/html/rfc7523)) for Machine-to-Machine clients.

-What this means is that you have to send an JWT token, containing the [standard claims for access tokens](../../apis/openidoauth/claims) and that is signed with your private key, to the token endpoint to request the access token. We will see how this works in another module about Service Accounts.
+What this means is that you have to send an JWT token, containing the [standard claims for access tokens](/apis/openidoauth/claims) and that is signed with your private key, to the token endpoint to request the access token. We will see how this works in another module about Service Accounts.

 If you don’t have any technical limitations, you should prefer this method over other methods.

@@ -11,9 +11,9 @@ It covers how to:

 Prerequisites:

- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects)
 - existing Atlassian Access setup, including verified domain

 > We have to switch between ZITADEL and Atlassian. If the headings begin with "ZITADEL" switch to the ZITADEL
@@ -2,7 +2,7 @@
 title: Connect with Auth0 through OIDC
 ---

-import CreateApp from "./application/_application.mdx";
+import CreateApp from "../application/_application.mdx";

 This guide shows how to enable login with ZITADEL on Auth0.

@@ -13,9 +13,9 @@ It covers how to:

 Prerequisites:

- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects)
 - existing Auth0 tenant as described [here](https://auth0.com/docs/get-started/auth0-overview/create-tenants)

 > We have to switch between ZITADEL and a Auth0. If the headings begin with "ZITADEL" switch to the ZITADEL Console and if the headings start with "Auth0" please switch to the Auth0 GUI.
@@ -11,9 +11,9 @@ It covers how to:

 Prerequisites:

- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects)
 - existing Auth0 tenant as described [here](https://auth0.com/docs/get-started/auth0-overview/create-tenants)

 > We have to switch between ZITADEL and a Auth0. If the headings begin with "ZITADEL" switch to the ZITADEL Console and
@@ -11,9 +11,9 @@ It covers how to:

 Prerequisites:

- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects)
 - prerequisites on AWS side [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/prereqs.html).
 - enabled AWS SSO [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/step1.html?icmpid=docs_sso_console)

@@ -11,9 +11,9 @@ It covers how to:

 Prerequisites:

- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects)
 - existing Gitlab SaaS Setup in the premium tier

 > We have to switch between ZITADEL and Gitlab. If the headings begin with "ZITADEL" switch to the ZITADEL
@@ -2,7 +2,7 @@
 title: Gitlab OmniAuth Provider
 ---

-import CreateApp from "./application/_application.mdx";
+import CreateApp from "../application/_application.mdx";


 This guide shows how to enable login with ZITADEL on self-hosted Gitlab instances.
@@ -14,9 +14,9 @@ It covers how to:

 Prerequisites:

- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects)
 - running Gitlab instance see [installation guide](https://docs.gitlab.com/ee/install/)

 <CreateApp appType="web" authType="code" appName="Gitlab" redirectURI="https://<your_gitlab_url>/users/auth/openid_connect/callback"/>
@@ -11,9 +11,9 @@ It covers how to:

 Prerequisites:

- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects)
 - existing Pingidentity environment [here](https://docs.pingidentity.com/bundle/pingone/page/wqe1564020490538.html)

 > We have to switch between ZITADEL and Ping Identity. If the headings begin with "ZITADEL" switch to the ZITADEL
@@ -79,7 +79,7 @@ Payload
 * `iat` is a unix timestamp of the creation signing time of the JWT, e.g. now and must not be older than 1 hour ago
 * `exp` is the unix timestamp of expiry of this assertion

-Please refer to [JWT_with_Private_Key](../../apis/openidoauth/authn-methods#jwt-with-private-key) in the documentation for further information.
+Please refer to [JWT_with_Private_Key](/apis/openidoauth/authn-methods#jwt-with-private-key) in the documentation for further information.

 If you use Go, you might want to use the [provided tool](https://github.com/zitadel/zitadel-tools) to generate a JWT from the downloaded json. There are many [libraries](https://jwt.io/#libraries-io) to generate and sign JWT.

@@ -97,7 +97,7 @@ curl --request POST \
 ```

 * `grant_type` should be set to `urn:ietf:params:oauth:grant-type:jwt-bearer`
-* `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
+* `scope` should contain any [Scopes](/apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
 * `assertion` is the encoded value of the JWT that was signed with your private key from the prior step

 You should receive a successful response with `access_token`,  `token_type` and time to expiry in seconds as `expires_in`.
@@ -133,7 +133,7 @@ You can configure all kinds of external identity providers for identity brokerin
 Create a new identity provider configuration and enable it in the list afterwards.

 For a detailed guide about how to configure a new identity provider for identity brokering have a look at our guide:
-[Identity Brokering](../../../guides/integrate/identity-brokering)
+[Identity Brokering](/guides/integrate/identity-providers/introduction.md)

 ## Password Complexity

@@ -171,7 +171,7 @@ In the domain policy you have two different settings.
 One is the "user_login_must_be_domain", by setting this all the users within an organisation will be suffixed with the domain of the organisation.

 The second is "validate_org_domains" if this is set to true all created domains on an organisation must be verified per acme challenge.
-More about how to verify a domain [here](../../../guides/manage/console/organizations#domain-verification-and-primary-domain).
+More about how to verify a domain [here](/guides/manage/console/organizations#domain-verification-and-primary-domain).
 If it is set to false, all registered domain will automatically be created as verified and the users will be able to use the domain for login.

 ### Use email as username
@@ -11,7 +11,7 @@ Before you start, make sure you have everything set up correctly.

 - You need to be at least a ZITADEL _ORG_OWNER_
 - Your ZITADEL organization needs to have the actions feature enabled. <!-- TODO: How to enable it for SaaS ZITADEL? -->
- [Your ZITADEL organization needs to have at least one external identity provider enabled](../../integrate/identity-brokering)
+- [Your ZITADEL organization needs to have at least one external identity provider enabled](../../integrate/identity-providers/introduction.md)
 - [You need to have at least one role configured for a project](../console/projects)

 ## Copy some information for the action
@@ -35,7 +35,7 @@ https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js

 ## Run the action when a user registers

-Now, make the action hook into the [external authentication flow](../../../apis/actions/external-authentication).
+Now, make the action hook into the [external authentication flow](/apis/actions/external-authentication).

 1. In the **Flows <i className="las la-exchange-alt"></i>** section, select the **+ New** button.
 1. Select the **Flow Type** _External Authentication_.
@@ -49,5 +49,5 @@ New users automatically are assiged a role now if they register by authenticatin

 ## What's next?

- [Read more about the concepts around actions](../../../concepts/features/actions)
- [Read more about all the options you have with actions](../../../apis/actions/introduction)
+- [Read more about the concepts around actions](/concepts/features/actions)
+- [Read more about all the options you have with actions](/apis/actions/introduction)
@@ -43,7 +43,7 @@ If you like to trigger your settings for your applications you have different po

 ### 1. Primary Domain Scope

-Send a [reserved scope](../../../apis/openidoauth/scopes) with your [authorization request](../../integrate/login-users#auth-request) to trigger your organization.
+Send a [reserved scope](/apis/openidoauth/scopes) with your [authorization request](../../integrate/login-users#auth-request) to trigger your organization.
 The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login.

 You can use our [OpenID Authentication Request Playground](/apis/openidoauth/authrequest) to learn more about how to trigger an [organization's policies and branding](/apis/openidoauth/authrequest#organization-policies-and-branding).
@@ -24,7 +24,7 @@ Typical examples for user metadata include:

 ### Add metadata to a user

- [Add metadata](../../../manuals/user-profile#metadata) to a user
+- [Add metadata](/guides/manage/customize/user-metadata) to a user
 - Make sure you will use this user to login during later steps

 ## Requesting a token
@@ -47,7 +47,7 @@ export ZITADEL_DOMAIN="https://...asd.zitadel.cloud"
 <Tabs>
 <TabItem value="go" label="Go" default>

-Grab zitadel-tools to create the [required string](../../../apis/openidoauth/authn-methods#client-secret-basic) for Basic authentication:
+Grab zitadel-tools to create the [required string](/apis/openidoauth/authn-methods#client-secret-basic) for Basic authentication:

 ```bash
 git clone [email protected]:zitadel/zitadel-tools.git
@@ -93,7 +93,7 @@ Export the result to the environment variable `BASIC_AUTH`.

 <TabItem value="manually" label="Manually">

-You need to create a string as described [here](../../../apis/openidoauth/authn-methods#client-secret-basic).
+You need to create a string as described [here](/apis/openidoauth/authn-methods#client-secret-basic).

 Use a programming language of your choice or manually create the strings with online tools (don't use these secrets for production) like: 

@@ -107,7 +107,7 @@ Export the result to the environment variable `BASIC_AUTH`.

 ### Create Auth Request

-You need to create a valid auth request, including the reserved scope `urn:zitadel:iam:user:metadata`. Please refer to our API documentation for more information about [reserved scopes](../../../apis/openidoauth/scopes#reserved-scopes) or try it out in our [OIDC Authrequest Playground](/apis/openidoauth/authrequest?scope=openid%20email%20profile%20urn%3Azitadel%3Aiam%3Auser%3Ametadata).
+You need to create a valid auth request, including the reserved scope `urn:zitadel:iam:user:metadata`. Please refer to our API documentation for more information about [reserved scopes](/apis/openidoauth/scopes#reserved-scopes) or try it out in our [OIDC Authrequest Playground](/apis/openidoauth/authrequest?scope=openid%20email%20profile%20urn%3Azitadel%3Aiam%3Auser%3Ametadata).

 Login with the user to which you have added the metadata. After the login you will be redirected.

@@ -31,7 +31,7 @@ If nothing is requested, the type will not be restricted and all possibilities o

 If you already have a user in ZITADEL, it is possible to add passwordless later.

-[Add Passwordless Registration ](../../../apis/mgmt)
+[Add Passwordless Registration ](/apis/mgmt)

 Send the user_id in the request and you will get a link and an expiration as response.
 You can then customize the link the same as described above in the creation process.
@@ -39,7 +39,7 @@ You can then customize the link the same as described above in the creation proc
 The second possibility is to send the link directly to the user per email.
 Use the following request in that case:

-[Send Passwordless Registration ](../../../apis/mgmt)
+[Send Passwordless Registration ](/apis/mgmt)

 ## Verified Email Address

@@ -4,16 +4,23 @@ title: Overview

 Most applications need to know the identity of a user for access control, to securely store their data in the cloud, and provide the same personalized experience across all of the user's devices.

-ZITADEL provides backend services, easy-to-use SDKs, and ready-made UI libraries to authenticate users in your application. It supports authentication using passwords and applies additional security with the help of a second factor, for example, OTP, to ensure safe and secure access.
-It additionally leverages industry standards like OAuth 2.0 and OpenID Connect such that it can be easily integrated into your custom backend.
+With ZITADEL you can rely on a hardened and extensible turnkey solution to solve all of your authentication and authorization needs.
+We provide you with a wide range of out of the box features to accelerate your project. Multi-tenancy with branding customization, secure login, self-service, OpenID Connect, OAuth2.x, SAML2, Passwordless with FIDO2 (including Passkeys), OTP, U2F, and an unlimited audit trail is there for you, ready to use.
+Execute custom code on selected events within ZITADEL to ensure perfect compatibility with your unique and complex software landscape and data models.
+
+## Get Started
+
+### Quick Start Guide
+
+Follow our [Quick Start Guide](/guides/start/quickstart).
+
+### Cloud or Self-Hosting

 ZITADEL can be used in two ways:
+
 - Use the ZITADEL Cloud, our public cloud service. Use the free tier to get started in minutes.
 - Deploy a self-hosted ZITADEL for full control, wherever you like.

-
-## Help me choose
-
 If you are unsure, opt for the gracious free tier of [ZITADEL Cloud](./manage/cloud/overview).

 Choose [ZITADEL Cloud](./manage/cloud/overview) if you want:
@@ -29,9 +36,14 @@ Choose [ZITADEL Self-Hosted](/self-hosting/deploy/overview) if you want:
 - To run ZITADEL in air-gapped or regulated environments
 - Flexibility when you deploy updates

-:::info
-Support is available either through the opensource community or a support contract.
-:::
+## Get Help

+Join our [Discord Chat](https://zitadel.com/chat) or open a [Discussion](https://github.com/zitadel/zitadel/discussions) on Github to get help from the community and the team behind ZITADEL.

-With our guides, you will learn everything you need to know about specific topics. To get started, jump directly to the [get started](./start/quickstart) docs.
+Cloud and Enterprise customers can additionally reach us privately via the [Support communication channels](/legal/support-services).
+
+## Contribute
+
+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 [contribute a corresponding change](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md).
@@ -29,7 +29,7 @@ You can read more about how ZITADEL handles usernames [here](../manage/console/o
 ZITADEL gives you a basic storage for users and manages phone and email addresses. It also allows you to store your own application data such as preferences or external identifiers to the metadata of a user.

 If you are migrating an existing project and you already have an external identity store you can consider bulk importing your user datasets.
-Read our [Management API definitions](../../apis/mgmt) for more info. If the users email is not verified or no password is set, a initialization mail will be send.
+Read our [Management API definitions](/apis/mgmt) for more info. If the users email is not verified or no password is set, a initialization mail will be send.

 :::info
 Requests to the management API are rate limited. Read our [Rate limit Policy](../../legal/rate-limit-policy) for more info.
@@ -1,5 +1,6 @@
 ---
 title: How to configure ZITADEL for your scenario
+sidebar_label: FAQ Configurations
 ---

 Each customer does have different needs and use-cases. In ZITADEL you are able to configure your settings depending on your needs.
@@ -14,13 +15,13 @@ If a user of this organization wants to login, you don't want them to enter thei
 ### Settings

 1. Go to the "Identity Providers" Settings of the organization
-2. Configure the needed identity provider: Read this [guide](../integrate/identity-brokering.md) if you don't know how
+2. Configure the needed identity provider: Read this [guide](../integrate/identity-providers/introduction.md) if you don't know how
 3. Go to the "Login Behavior and Security" settings of the organization
 4. Disable "Username Password Allowed" and enable "External IDP allowed" in the Advanced Section

 Now your application can send either the organizations id (`urn:zitadel:iam:org:id:{id}`) or organizations primary domain (`urn:zitadel:iam:org:domain:primary:{domainname}`) scope on your authorization request to identify on which organization the users should be logged in.

-More about the [scopes](../../apis/openidoauth/scopes#reserved-scopes)
+More about the [scopes](/apis/openidoauth/scopes#reserved-scopes)

 ## Custom Application Domain per Organization

@@ -45,7 +46,7 @@ This will have the following impacts:
 - Only allow users from selected organization to login

 To request the organization send either the the organization id (`urn:zitadel:iam:org:id:{id}`) or organization primary domain (`urn:zitadel:iam:org:domain:primary:{domainname}`) scope on your authentication request from your application.
-More about the [scopes](../../apis/openidoauth/scopes#reserved-scopes)
+More about the [scopes](/apis/openidoauth/scopes#reserved-scopes)

 ## Use email to login

@@ -1,36 +0,0 @@
---
-title: Application Support Trainings
---
-
-## ZITADEL DevOps
-
-In this session your second level support and operations team will gain an understanding on how to extract relevant information for technical support questions and root cause analysis. We will also present our DevOps best practices and answer your questions.
-
-**Audience**: 2nd Level Support Staff, Operations
-**Duration**: 0.5 day
-
-**Topics covered**:
-
- Event types
- Database schemas and compute models
- Accessing database
- Observability (Logs, Errors, Metrics, Tracing)
- Operations best practices (Deployment, Backup, Networking etc.)
- Q&A
-
-## ZITADEL Administrator
-
-In this hands-on training your employees will get a complete overview of the system and learn how to configure and use ZITADEL. Your support staff will gain the required knowledge to provide user-support, while your solution owners gain an understanding about integration of clients.
-
-**Audience**: 1st / 2nd Level Support Staff, Solution Owner, QA Manager (optional)  
-**Duration**: 0.5 days
-
-**Topics covered**:
-
- IAM Configuration
- Walk-though all features
- Users / Manuals
- APIs
- Validation of tokens
- Client integration best-practices
- Q&A
@@ -1,29 +0,0 @@
---
-title: Introduction
---
-
-The following pages describe the the trainings provided by ZITADEL. These trainings are intended for onboarding and during the course of a Support Program.
-
-Training should be held as block-sessions with the relevant staff from your organization.
-
-## Onboarding Project
-
-You receive professional onboarding support from our engineers, who help you to setup and configure ZITADEL on your infrastructure.
-
-[More information](project)
-
-## Application Support Trainings
-
-With the application support trainings we provide the initial knowledge transfer to manage and support ZITADEL. The trainings are held as block-sessions with relevant staff from your organization. Prices are flat-fee, excl. expenses.
-
-* [ZITADEL DevOps](application#zitadel-devops)
-* [ZITADEL Administrator](application#zitadel-administrator)
-
-## Recurring Trainings
-
-While you can benefit from a technical account manager during your term, these trainings are designed to onboard new staff or update staff about larger changes to the platform. Prices are flat-fee, excl. expenses.
-
-* [ZITADEL Support Refresher](recurring#zitadel-support-refresher)
-* [ZITADEL Support Onboarding](recurring#zitadel-support-onboarding)
-
-In case you have any questions please [get in touch](https://zitadel.com/contact).
@@ -1,35 +0,0 @@
---
-title: Onboarding Project
---
-
-Effort required during depends on the complexity of your infrastructure and the overall setup. With a Multi-Zone Setup (excl. Multi-Region), support during this phase requires around 10-25h over 2 weeks. Actual effort is based on time and material.
-
-Scope of the project is agreed on individual basis.
-
-## In Scope
-
- Check prerequisites and architecture
- Troubleshoot installation and configuration of ZITADEL
- Troubleshoot and configuration connectivity to the database
- Functional testing of the ZITADEL instance
-
-## Out of Scope
-
- Running multiple ZITADEL instances on the same cluster
- Integration into internal monitoring and alerting
- Multi-cluster architecture deployments
- DNS, Network and Firewall configuration
- Customer-specific Kubernetes configuration needs
- Changes for specific environments
- Performance testing
- Production deployment
- Application-side coding, configuration, or tuning
- Changes or configuration on assets used in ZITADEL
- Setting up or maintaining backup storage
-
-## Prerequisites
-
- Running Kubernetes with possibility to deploy to namespaces
- Inbound and outbound HTTP/2 traffic possible
- For being able to send SMS, we need a Twilio sender name, SID and an auth token
- ZITADEL also needs to connect to an email relay of your choice. We need the SMTP host, user and app key as well as the ZITADEL emails sender address and name.
@@ -1,33 +0,0 @@
---
-title: Recurring Trainings
---
-
-## ZITADEL Support Refresher
-
-In this session you can refresh knowledge about existing and gain experience with new features of ZITADEL to keep the quality of your support high. We recommend an half day training per support staff.
-
-**Audience**: 1st / 2nd Level Support Staff, Solution Owner, QA Manager (optional)  
-**Duration**: 0.5 day / support staff
-
-**Topics covered**:
-
-* Walk-through new features
-* Review of difficult support issues
-* Review of customer feedback
-* Q&A
-
-## ZITADEL Support Onboarding
-
-In this hands-on training new support staff will get an overview of the system and learn how to configure and use ZITADEL to provide support for users.
-
-**Audience**: 1st / 2nd Level Support Staff, Solution Owner, QA Manager (optional)  
-**Duration**: 0.5 days / support staff
-
-**Topics covered**:
-
-* Event types
-* Accessing database
-* Logs and Errors
-* Validation of tokens
-* Walk-through key features
-* Q&A