docs(integrate): improve service user authentication (#7492)

* service users

* wip

* wip

* wip

* lower case titles

* wip

* wip

* private key jwt

* wip

* wip

* token introspection

* zitadel apis

* expiration

* replace mermaid with svg

* Apply suggestions from code review

Co-authored-by: Fabi <fabienne@zitadel.com>

* Apply suggestions from code review

* boulevard of broken links

* my hrefs will go on

* docs: add token type to client credential

* Update docs/docs/apis/introduction.mdx

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/service-users/authenticate-service-users.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/service-users/authenticate-service-users.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/service-users/authenticate-service-users.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/service-users/private-key-jwt.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/service-users/private-key-jwt.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/service-users/authenticate-service-users.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/service-users/client-credentials.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/service-users/client-credentials.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/_accessing_zitadel_api.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

Co-authored-by: Florian Forster <florian@zitadel.com>

* docs: add token type to client credential

---------

Co-authored-by: Fabi <fabienne@zitadel.com>
Co-authored-by: Fabienne <fabienne.gerschwiler@gmail.com>
Co-authored-by: Florian Forster <florian@zitadel.com>
Co-authored-by: Livio Spring <livio.a@gmail.com>

docs/docs/apis/introduction.mdx

@@ -14,8 +14,21 @@ The [OpenID Connect & OAuth endpoints](/docs/apis/openidoauth/endpoints) and [SA
 
 ## Authentication & authorization
 
+### Authentication for human users (interactive)
+
 ZITADEL implements industry standards such as OpenID Connect, OAuth 2.0, or SAML for authentication.
-Please refer to our guides how to [authenticate users](/docs/guides/integrate/login/login-users) through an interactive authentication process and how to [authenticate service users](/docs/guides/integrate/serviceusers) with a programmatic authentication.
+Please refer to our guides how to [authenticate users](/docs/guides/integrate/login/login-users) through an interactive authentication process.
+
+For user authentication on devices with limited accessibility (eg, SmartTV, Smart Watch etc.) use the [device authorization grant](/docs/guides/integrate/login/oidc/device-authorization).
+
+Additionally, you can use the [session API](../apis/resources/session_service/) to authenticate users, for example by building a [custom login UI](/docs/guides/integrate/login-ui/).
+
+### Authenticate service users and machines
+
+Service users allow for machine-to-machine (M2M) communication.
+Follow the guides to learn how to [authenticate service users](/docs/guides/integrate/service-users/authenticate-service-users).
+
+Accessing the ZITADEL APIs through a service user might require additional steps, please follow the guide on how to [access ZITADEL APIs](../guides/integrate/zitadel-apis/access-zitadel-apis) to include the correct audience scope in your requests.
 
 ### OpenID Connect & OAuth
 
@@ -163,7 +176,7 @@ API Reference:
 
 This API is intended to manage the different ZITADEL instances within the system.
 
-Checkout the guide how to [access the ZITADEL System API](/guides/integrate/access-zitadel-system-api).
+Checkout the guide how to [access the ZITADEL System API](/docs/guides/integrate/zitadel-apis/access-zitadel-system-api).
 
 </div>
 <div className="apicard-right">

docs/docs/concepts/features/audit-trail.md

@@ -35,10 +35,10 @@ Go to your instance settings and then click on the Tab **Events** to open the Ev
 
 Since everything that is available in Console can also be called with our APIs, you can access all events and audit data trough our APIs:
 
-- [Event API Guide](/docs/guides/integrate/event-api)
+- [Event API Guide](/docs/guides/integrate/zitadel-apis/event-api)
 - [API Documentation](/docs/category/apis/resources/admin/events)
 
-Access to the API is possible with a [Service User](/docs/guides/integrate/serviceusers) account, allowing you to integrate the events with your own business logic.
+Access to the API is possible with a [Service User](/docs/guides/integrate/service-users/authenticate-service-users) account, allowing you to integrate the events with your own business logic.
 
 ## Using logs in external systems
 

docs/docs/concepts/features/selfservice.md

@@ -68,7 +68,7 @@ Given an external identity provider is configured on the instance or on the orga
 ### Machines
 
 Machine accounts can't use an interactive login but require other means of authentication, such as privately-signed JWT or personal access tokens.
-Read more about [Service Users](/guides/integrate/serviceusers) and recommended [OpenID Connect Flows](/guides/integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
+Read more about [Service Users](/guides/integrate/service-users/authenticate-service-users) and recommended [OpenID Connect Flows](/guides/integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
 
 ## Logout
 

docs/docs/examples/secure-api/python-flask.mdx

@@ -16,7 +16,7 @@ The API will validate the access token on the [introspect endpoint](https://zita
 
 The API application uses [Client Secret Basic](https://zitadel.com/docs/apis/openidoauth/authn-methods#client-secret-basic) to authenticate against ZITADEL and access the introspection endpoint.
 You can use any valid access_token from a user or service account to send requests to the example API.
-In this example we will use a service account with a [personal access token](https://zitadel.com/docs/guides/integrate/pat) which can be used directly to access the example API.
+In this example we will use a service account with a [personal access token](https://zitadel.com/docs/guides/integrate/service-users/personal-access-token) which can be used directly to access the example API.
 
 
 ## Running the example
@@ -191,7 +191,7 @@ CLIENT_SECRET = "NVAp70IqiGmJldbS...."
 
 ![Create a service user](/img/python-flask/3.png)
 
-1. Create a service user and a Personal Access Token (PAT) for that user by following [this guide](https://zitadel.com/docs/guides/integrate/pat#create-a-service-user-with-a-pat). 
+1. Create a service user and a Personal Access Token (PAT) for that user by following [this guide](https://zitadel.com/docs/guides/integrate/service-users/personal-access-token#create-a-service-user-with-a-pat). 
 2. To enable authorization, follow [this guide](https://zitadel.com/docs/guides/manage/console/roles) to create a role `read:messages` on your project. 
 3. Next, create an authorization for the service user you created by adding the role `read:messages` to the user. Follow this [guide](https://zitadel.com/docs/guides/manage/console/roles#authorizations) for more information on creating an authorization. 
 

docs/docs/guides/integrate/access-zitadel-apis.md

@@ -1,81 +0,0 @@
----
-title: Access ZITADEL APIs
----
-
-:::note
-This guide focuses on the Admin, Auth and Management APIs. To access the ZITADEL System API, please checkout [this guide](./access-zitadel-system-api).
-:::
-
-## ZITADEL Managers
-
-ZITADEL Managers are Users who have permission to manage ZITADEL itself. There are some different levels for managers.
-
-- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole instance.
-- **Org Managers**: Managers in the Organization Level are able to manage everything within the granted Organization.
-- **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)
-
-## Add ORG_OWNER to Service User
-
-Make sure you have a Service User with a Key. (For more detailed informations about creating a service user go to [Service User](serviceusers))
-
-1. Navigate to Organization Detail
-2. Click the **+** button in the right part of console, in the managers part of details
-3. Search the user and select it
-4. Choose the role ORG_OWNER
-
-![Add Org Manager](/img/console_org_manager_add.gif)
-
-## Authenticating a service user
-
-In ZITADEL we use the `urn:ietf:params:oauth:grant-type:jwt-bearer` (**“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523)) authorization grant for this non-interactive authentication.
-This is already described in the [Service User](./serviceusers), so make sure you follow this guide.
-
-### Request an OAuth token, with audience for ZITADEL
-
-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)
-
-Use the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to include the ZITADEL project id in your audience
-
-```bash
-curl --request POST \
-  --url $CUSTOM-DOMAIN/oauth/v2/token \
-  --header 'Content-Type: application/x-www-form-urlencoded' \
-  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
-  --data scope='openid profile email urn:zitadel:iam:org:project:id:zitadel:aud' \
-  --data assertion=eyJ0eXAiOiJKV1QiL...
-```
-
-- `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`
-- `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`.
-
-```bash
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
-  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
-  "token_type": "Bearer",
-  "expires_in": 43199
-}
-```
-
-With this token you are allowed to access the [ZITADEL APIs](/apis/introduction) .
-
-## Summary
-
-- Grant a user for ZITADEL
-- Because there is no interactive logon, you need to use a JWT signed with your private key to authorize the user
-- With a custom scope (`urn:zitadel:iam:org:project:id:zitadel:aud`) you can access ZITADEL APIs
-
-Where to go from here:
-
-- [ZITADEL API Documentation](/apis/introduction)

docs/docs/guides/integrate/client-credentials.md

@@ -1,88 +0,0 @@
----
-title: Client Credentials with Service Users
----
-
-This is a guide on how to use Client Credentials with service users in ZITADEL. You can read more about users [here](/concepts/structure/users.md).
-
-In ZITADEL, the Client Credentials grant can be used for this non-interactive authentication as alternative to the [JWT profile authentication](serviceusers).
-
-## Create a Service User with a Secret
-
-1. Navigate to Service Users
-2. Click on **New**
-3. Enter a username and a display name
-4. Click on **Create**
-5. Open **Actions** in the top right corner and click on **Generate Client Secret**
-6. Copy the **ClientID** and **ClientSecret** from the dialog
-
-:::note
-Be sure to copy in particular the ClientSecret. You won't be able to retrieve it again.
-If you lose it, you will have to generate a new one.
-:::
-
-![Create new service user](/img/console_serviceusers_secret.gif)
-
-## Grant role for ZITADEL
-
-To be able to access the ZITADEL APIs your service user needs permissions to ZITADEL.
-
-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](/guides/manage/console/managers))
-
-![Add org owner to service user](/img/guides/console-service-user-org-owner.gif)
-
-## Authenticating a service user
-
-In this step we will authenticate a service user and receive an access_token to use against the ZITADEL API.
-
-You will need to craft a POST request to ZITADEL's token endpoint:
-
-```bash
-curl --request POST \
-  --url https://$CUSTOM-DOMAIN/oauth/v2/token \
-  --header 'Content-Type: application/x-www-form-urlencoded' \
-  --header 'Authorization: Basic ${BASIC_AUTH}' \
-  --data grant_type=client_credentials \
-  --data scope='openid profile email urn:zitadel:iam:org:project:id:zitadel:aud'
-```
-
-* `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`
-  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`.
-
-```bash
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
-  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
-  "token_type": "Bearer",
-  "expires_in": 43199
-}
-```
-
-## Call ZITADEL API with Token
-
-Because the received Token includes the `urn:zitadel:iam:org:project:id:zitadel:aud` scope, we can send it in your requests to the ZITADEL API as Authorization Header.
-In this example we read the organization of the service user.
-
-```bash
-curl --request GET \
-  --url $CUSTOM-DOMAIN/management/v1/orgs/me \
-  --header 'Authorization: Bearer ${TOKEN}' 
-```
-
-## Summary
-
-* With service users you can secure machine-to-machine communication
-* Client Credentials provide an alternative way to JWT Profile for service user authentication
-* After successful authorization you can use an access token like for human users
-
-Where to go from here:
-
-* Management API
-* Securing backend API

docs/docs/guides/integrate/external-audit-log.md

@@ -32,7 +32,7 @@ This API offers granular control through various filters, enabling you to:
 - **Target Aggregates**: Narrow down the data scope by filtering for events related to particular organizations, projects, or users.
 - **Define Time Frames**: Retrieve audit logs for precise time periods, allowing you to schedule data retrieval at desired intervals (e.g., hourly) and analyze activity within specific windows.
 
-You can find a comprehensive guide on how to use the events API for different use cases here: [Get Events from ZITADEL](/docs/guides/integrate/event-api)
+You can find a comprehensive guide on how to use the events API for different use cases here: [Get Events from ZITADEL](/docs/guides/integrate/zitadel-apis/event-api)
 
 ### Cockroach Change Data Capture
 

docs/docs/guides/integrate/pat.md

@@ -1,46 +0,0 @@
----
-title: ZITADEL's Personal Access Tokens(PATs)
-sidebar_label: Personal Access Tokens(PATs)
----
-
-
-A Personal Access Token (PAT) is a ready to use token which can be used as _Authorization_ header.
-At the moment ZITADEL only allows PATs for machine accounts (service users).
-
-It is an alternative to the JWT profile authentication where the service user has a key to authenticate. Read more about that [here](serviceusers)
-
-## Create a Service User with a PAT
-
-
-1. Navigate to Service Users
-2. Click on **New**
-3. Enter a user name and a display name
-4. Click on the Personal Access Token menu point in the detail of your user
-5. Click on **New**
-6. You can either set an expiration date or leave it empty if you don't want it to expire
-7. Copy the token from the dialog (You will not see this again)
-
-![Create new service user](/img/guides/console-service-user-pat.gif)
-
-## Grant role for ZITADEL
-
-To be able to access the ZITADEL APIs your service user needs permissions to ZITADEL.
-
-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))
-
-![Add org owner to service user](/img/guides/console-service-user-org-owner.gif)
-
-
-## Call ZITADEL API with PAT
-
-Because the PAT is a ready to use Token, you can add it as Authorization Header and send it in your requests to the ZITADEL API.
-In this example we read the organization of the service user.
-
-```bash
-curl --request GET \
-  --url $CUSTOM-DOMAIN/management/v1/orgs/me \
-  --header 'Authorization: Bearer {PAT}' 
-```

docs/docs/guides/integrate/private-key-jwt.md

@@ -1,157 +0,0 @@
----
-title: Service Users in ZITADEL
-sidebar_label: Service Users
----
-
-This is a guide on how to create service users in ZITADEL. You can read more about users [here](/concepts/structure/users.md).
-
-## Create a Service User
-
-1. Navigate to Service Users
-2. Click on **New**
-3. Enter a user name and a display name
-
-![Create new service user](/img/console_serviceusers_create.gif)
-
-## Authenticating a service user
-
-In ZITADEL we use the `urn:ietf:params:oauth:grant-type:jwt-bearer` (**“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523)) authorization grant for this non-interactive authentication.
-
-You need to follow these steps to authenticate a service user and receive an access token:
-
-1. Generate a private-public key pair in ZITADEL
-2. Create a JSON Web Token (JWT) and sign with private key
-3. With this JWT, request an OAuth token from ZITADEL
-
-With this token you can make subsequent requests, just like a human user.
-
-## Get an access token
-
-In this step we will authenticate a service user and receive an access_token to use against the API.
-
-> **Information:** Are you stuck? Don't hesitate to reach out to us on [Github Discussions](https://github.com/zitadel/zitadel/discussions) or [contact us](https://zitadel.com/contact/) privately.
-
-### 1. Generate a private-public key pair in ZITADEL
-
-Select your service user and in the section KEYS click **New**. Enter an optional expiration date and click **Add**. Make sure to download the json by clicking **Download**.
-
-:::note
-If you specify an expiration date, note that the key will expire at midnight that day
-:::
-
-![Create private key](/img/console_serviceusers_new_key.gif)
-
-The downloaded json should look something like outlined below. The value of `key` contains the _private_ key for your service account. Please make sure to keep this key securely stored and handle with care. The public key is automatically stored in ZITADEL.
-
-```json
-{
-  "type": "serviceaccount",
-  "keyId": "100509901696068329",
-  "key": "-----BEGIN RSA PRIVATE KEY----- [...] -----END RSA PRIVATE KEY-----\n",
-  "userId": "100507859606888466"
-}
-```
-
-### 2. Create a JWT and sign with private key
-
-You need to create a JWT with the following header and payload and sign it with the RS256 algorithm.
-
-Header
-
-```json
-{
-  "alg": "RS256",
-  "kid": "100509901696068329"
-}
-```
-
-Make sure to include `kid` in the header with the value of `keyId` from the downloaded JSON.
-
-Payload
-
-```json
-{
-    "iss": "100507859606888466",
-    "sub": "100507859606888466",
-    "aud": "https://$CUSTOM-DOMAIN",
-    "iat": [Current UTC timestamp, e.g. 1605179982, max. 1 hour ago],
-    "exp": [UTC timestamp, e.g. 1605183582]
-}
-```
-
-- `iss` represents the requesting party, i.e. the owner of the private key. In this case the value of `userId` from the downloaded JSON.
-- `sub` represents the application. Set the value also to the value of `userId`
-- `aud` must be ZITADEL's issuing domain
-- `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.
-
-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.
-
-### 3. With this JWT, request an OAuth token from ZITADEL
-
-With the encoded JWT from the prior step, you will need to craft a POST request to ZITADEL's token endpoint:
-
-```bash
-curl --request POST \
-  --url https:/$CUSTOM-DOMAIN/oauth/v2/token \
-  --header 'Content-Type: application/x-www-form-urlencoded' \
-  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
-  --data scope='openid profile email' \
-  --data assertion=eyJ0eXAiOiJKV1QiL...
-```
-
-If you want to access the ZITADEL API with this access token, you have to add `urn:zitadel:iam:org:project:id:zitadel:aud` to the list of scopes.
-
-- `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`
-- `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`.
-
-```bash
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
-  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
-  "token_type": "Bearer",
-  "expires_in": 43199
-}
-```
-
-### 4. Verify that you have a valid access token
-
-For this example let's call the userinfo endpoint to verify that our access token works.
-
-```bash
-curl --request POST \
-  --url $CUSTOM-DOMAIN/oidc/v1/userinfo \
-  --header 'Content-Type: application/x-www-form-urlencoded' \
-  --header 'Authorization: Bearer MtjHodGy4zxKylDOhg6kW90WeEQs2q...'
-```
-
-You should receive a response with your service user's information.
-
-```bash
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
-  "name": "MyServiceUser",
-  "preferred_username": "service_user@$CUSTOM-DOMAIN",
-  "updated_at": 1616417938
-}
-```
-
-## Summary
-
-- With service users you can secure machine-to-machine communication
-- Because there is no interactive logon, you need to use a JWT signed with your private key to authorize the user
-- After successful authorization you can use an access token like for human users
-
-Where to go from here:
-
-- Management API
-- Securing backend API

docs/docs/guides/integrate/retrieve-user-roles.md

@@ -32,7 +32,7 @@ You must first of all generate a token for the user. For human users, the typica
 How to generate a token: 
 
 - [Generate tokens for human users](/docs/guides/integrate/login/oidc/login-users)
-- [Generate tokens for service users](/docs/guides/integrate/serviceusers)
+- [Generate tokens for service users](/docs/guides/integrate/service-users/authenticate-service-users)
 
 In order to access role information via the token you must include the right audience and the necessary role claims in the scope and/or select the required role settings in the ZITADEL console before requesting the token. 
 

docs/docs/guides/integrate/service-users/authenticate-service-users.md

@@ -0,0 +1,137 @@
+---
+title: Authenticate service users and client applications
+sidebar_label: Authenticate service users
+sidebar_position: 1
+---
+
+This guide explains ZITADEL service users and their role in facilitating secure machine-to-machine communication within your applications.
+
+## What are Service Users?
+
+Service users in ZITADEL represent **non-human entities** within your system.
+They are ideal for scenarios involving secure communication between applications, particularly when interacting with backend services or APIs.
+Service users in combination with [Manager](/concepts/structure/managers) permissions are used to access ZITADEL's APIs, for example, to manage user resources.
+Unlike regular human users, service users don't rely on traditional login methods (e.g., username/password) and require alternative authentication mechanisms.
+
+## Benefits of using Service Users
+
+### Enhanced security
+
+* **Principle of Least Privilege:** Grant service users only the minimum permissions they need, minimizing potential damage in case of compromise.
+* **Distinct Credentials:** Avoid embedding sensitive credentials like API keys directly in code. Service user credentials can be rotated independently.
+
+### Segregated authorization
+
+Manage authorization for service users separately from human users, providing an extra layer of control.
+
+### API and backend access
+
+Service users offer a secure way to authenticate and access various API endpoints and protected backend services.
+
+You can [use service users to access ZITADEL APIs](../zitadel-apis/access-zitadel-apis), follow the guides to learn how to access the different ZITADEL APIs.
+While you can define the scopes and required information in your requests for your applications API endpoints, when using the ZITADEL APIs, you must include the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to gain access.
+
+### Improved auditability
+
+Actions performed by service users are clearly identifiable in logs, facilitating easier auditing and tracing.
+
+Using the [Event API](../zitadel-apis/event-api) you can use these logs for further analysis or to integrate the logs with [external SOC / SIEM](../external-audit-log) systems.
+
+## Authentication methods
+
+ZITADEL supports two primary authentication methods for service users:
+
+### Private key JWT authentication
+
+#### How private key JWT authentication works
+
+* Generate a private/public key pair associated with the service user.
+* Sign JWTs with the private key.
+* ZITADEL validates the signature using the service user's public key.
+* JWTs can include expiration dates and scopes to control access.
+
+Follow our guide on using [private key JWT client authentication](./private-key-jwt) to get started authenticating service users and clients.
+
+#### Benefits of private key JWT authentication
+
+* **Decentralized Verification:** No need for constant server calls, improving performance and scalability.
+* **Flexibility and Control:** Define scopes and expiration within the JWT itself for granular access control.
+* **Stateless:** The server doesn't need to maintain a session state, simplifying server implementation.
+
+#### Drawbacks of private key JWT authentication
+
+* **Complexity:** Slightly more complex to implement compared to other methods, requiring knowledge of JWT and digital signing.
+* **Revocation:** Invalidating a JWT before its expiry can be challenging; blacklisting mechanisms might be required. 
+
+#### Security considerations when using private key JWT authentication
+
+* **Secure Key Storage:** The private key used for signing must be stored with the highest level of security. Compromise could allow attackers to forge tokens.
+* **Short Expirations:** Implementing short expiration durations for JWTs helps limit the impact of stolen tokens.
+
+### Client credentials grant
+
+* Presents a client ID and client secret associated with the service user.
+* Simpler than the JWT profile in specific scenarios.
+
+Follow our guide on using [client credentials grant](./client-credentials) to get started authenticating service users and clients.
+
+This method is still available in ZITADEL but is generally considered less secure than JWT due to:
+
+* **Centralized Validation:** Relies on the server to verify credentials for every request, potentially impacting performance and requiring more server resources.
+* **Credentials Exposure:** Leaked client ID and secret could be used by attackers to impersonate the service user until rotation occurs.
+
+### Personal Access Tokens (PATs)
+
+* **Ready-to-use tokens:** Generated for specific service users and can be directly included in the authorization header of API requests.
+* **Currently available only for machine users** (service users) and not regular human users.
+
+Follow our guide on using [personal access tokens](./personal-access-token) to get started authenticating service users and clients.
+
+PAT offer some benefits, such as:
+
+* **Ease of Use:** Ready-to-use tokens, eliminating the need for complex signing logic.
+
+However, PATs also come with limitations:
+
+* **Centralized Validation:** Similar to Client Credentials, relying on the server for verification could impact performance under high load.
+* **Revocation:** Requires deleting the PAT directly, potentially causing downtime if not managed carefully.
+* **Leakage:** PATs are long-lived tokens that can be readily used in API calls, if leaked the attacker can access all resources until the PAT is expired or deleted. Private key JWT and client credentials create a short-lived access token instead.
+
+## Using Service Users
+
+1. **Creation:** Access the ZITADEL management console and create a new service user. Assign a descriptive name that reflects its purpose. Follow our detailed guide on [how to create service users](../../manage/console/users).
+2. **Credentials:** Choose your preferred authentication method (JWT or Client Credentials) and securely store the generated credentials (private key, client secret).
+3. **Making API Calls:** When your service needs to make an API call:
+    * **For JWT:** Generate and sign a JWT. Include it in the "Authorization" header of your API request.
+    * **For Client Credentials:** Include the client ID and client secret in your API request.
+    * **For PATs:** Include the PAT directly in the "Authorization" header of your API request.
+4. ZITADEL Verifies the credentials and authorizes the service user to perform the requested action based on its granted permissions.
+
+We have guides for the different authentication methods:
+
+- [Private key JWT authentication](private-key-jwt)
+- [Client credential authentication](client-credentials)
+- [Personal access token authentication](personal-access-token)
+
+## Important considerations
+
+* **Secure Credentials:** Treat service user credentials (private keys, client secrets) with utmost care. Store them securely, similar to any other sensitive information like API keys or passwords.
+* **Expiry Management:** Set appropriate expiration dates for JWTs and regularly rotate all credentials to maintain strong security practices.
+* **Permission Granting:** Adhere to the principle of least privilege by granting only the specific permissions required for a service user's function.
+
+## Choosing the right authentication method
+
+For most service user scenarios in ZITADEL, [private key JWT authentication](./private-key-jwt.md) is the recommended choice due to its benefits in security, performance, and control.
+However, [client credentials authentication](./client-credentials.md) might be considered in specific situations where simplicity and trust between servers are priorities.
+
+## Further resources
+
+* Read about the [different methods to authenticate service users](./authenticate-service-users)
+* [Service User API reference](/docs/category/apis/resources/mgmt/user-machine)
+* [OIDC JWT with private key](/docs/apis/openidoauth/authn-methods#jwt-with-private-key) authentication method reference
+* [Access ZITADEL APIs](../zitadel-apis/access-zitadel-apis)
+* Validate access tokens with [token introspection with private key jwt](../token-introspection/private-key-jwt.mdx)
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />

docs/docs/guides/integrate/service-users/client-credentials.md

@@ -0,0 +1,104 @@
+---
+title: Configure client credential authentication for service users
+sidebar_label: Client credential authentication
+sidebar_position: 3
+---
+
+This guide demonstrates how developers can leverage Client Credential authentication to secure communication between [service users](/concepts/structure/users) and client applications within ZITADEL.
+
+In ZITADEL, the Client Credentials Flow can be used for this [non-interactive authentication](authenticate-service-users) as alternative to the [JWT profile authentication](../service-users/authenticate-service-users).
+
+## Steps to authenticate a Service User with client credentials
+
+### 1. Create a Service User with a client secret
+
+1. Navigate to Service Users
+2. Click on **New**
+3. Enter a username and a display name
+4. Click on **Create**
+5. Open **Actions** in the top right corner and click on **Generate Client Secret**
+6. Copy the **ClientID** and **ClientSecret** from the dialog
+
+:::note
+Make sure to copy in particular the ClientSecret. You won't be able to retrieve it again.
+If you lose it, you will have to generate a new one.
+:::
+
+![Create new service user](/img/console_serviceusers_secret.gif)
+
+## 2. Authenticating a service user and request a token
+
+In this step, we will authenticate a service user and receive an access_token to use against the ZITADEL API.
+
+You will need to craft a POST request to ZITADEL's token endpoint:
+
+```bash
+curl --request POST \
+  --url https://$CUSTOM-DOMAIN/oauth/v2/token \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --header 'Authorization: Basic ${BASIC_AUTH}' \
+  --data grant_type=client_credentials \
+  --data scope='openid profile'
+```
+
+* `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`
+
+If you want to access ZITADEL APIs, make sure to include the required scopes `urn:zitadel:iam:org:project:id:zitadel:aud`.
+Read our guide [how to access ZITADEL APIs](../zitadel-apis/access-zitadel-apis) to learn more.
+
+You should receive a successful response with `access_token`,  `token_type` and time to expiry in seconds as `expires_in`.
+
+```bash
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
+  "token_type": "Bearer",
+  "expires_in": 43199
+}
+```
+
+Per default a service user will get an opaque access token.
+If you want to get a Jason Web Token (JWT) as an access token for your user, you can change the token type in the general settings of your service account.
+To learn more about opaque and JWT tokens read our [Opaque Tokens in ZITADEL: Enhancing Application Security](/docs/concepts/knowledge/opaque-tokens) Guide
+
+![Service User Token Type](/img/console_service_user_tokentype.png)
+
+### 3. Include the access token in the authorization header
+
+When making API requests on behalf of the service user, include the generated token in the "Authorization" header with the "Bearer" prefix.
+
+```bash
+curl --request POST \
+  --url $YOUR_API_ENDOINT \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --header 'Authorization: Bearer MtjHodGy4zxKylDOhg6kW90WeEQs2q...'
+```
+
+## Accessing ZITADEL APIs
+
+You might want to access ZITADEL APIs to manage resources, such as users, or to validate tokens sent to your backend service.
+Follow our guides on [how to access ZITADEL API](../zitadel-apis/access-zitadel-apis) to use the ZITADEL APIs with your service user using client credentials.
+
+### Token introspection
+
+Your API endpoint might receive tokens from users and need to validate the token with ZITADEL.
+In this case, your API needs to authenticate with ZITADEL and then do a token introspection.
+Follow our [guide on token introspection with client credentials](../token-introspection/basic-auth) to learn more.
+
+## Security considerations
+
+* **Store private keys securely:** **Never share or embed the private key in your code or application.** Consider using secure key management solutions.
+* **Set appropriate expiration times:** Limit the validity period of tokens to minimize the impact of potential compromise.
+
+By following these steps and adhering to security best practices, you can effectively secure service user and client application communication within ZITADEL using client credential authentication.
+
+## Notes
+
+* Read about the [different methods to authenticate service users](./authenticate-service-users)
+* [Service User API reference](/docs/category/apis/resources/mgmt/user-machine)
+* [OIDC client secret basic](/docs/apis/openidoauth/authn-methods#client-secret-basic) authentication method reference
+* [Access ZITADEL APIs](../zitadel-apis/access-zitadel-apis)
+* Validate access tokens with [token introspection with basic auth](../token-introspection/basic-auth)

docs/docs/guides/integrate/service-users/personal-access-token.md

@@ -0,0 +1,70 @@
+---
+title: Configure personal access token authentication for service users
+sidebar_label: Personal access token authentication
+sidebar_position: 3
+---
+
+A Personal Access Token (PAT) is a ready to use token which can be used as _Authorization_ header.
+At the moment ZITADEL only allows PATs for machine accounts (service users).
+
+It is an alternative to the [private key JWT profile authentication](private-key-jwt) and [client credentials authentication](client-credentials). Read more about that the different [authentication methods for service users](authenticate-service-users).
+
+## Create a Service User with a PAT
+
+1. Navigate to Service Users
+2. Click on **New**
+3. Enter a user name and a display name
+4. Click on the Personal Access Token menu point in the detail of your user
+5. Click on **New**
+6. You can either set an expiration date or leave it empty if you don't want it to expire
+7. Copy the token from the dialog (You will not see this again)
+
+![Create new service user](/img/guides/console-service-user-pat.gif)
+
+## Grant role for ZITADEL
+
+To be able to access the ZITADEL APIs your service user needs permissions to ZITADEL.
+
+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](/docs/guides/manage/console/managers))
+
+![Add org owner to service user](/img/guides/console-service-user-org-owner.gif)
+
+## Accessing ZITADEL APIs
+
+You might want to access ZITADEL APIs to manage resources, such as users, or to validate tokens sent to your backend service.
+Follow our guides on [how to access ZITADEL API](../zitadel-apis/access-zitadel-apis) to use the ZITADEL APIs with your service user.
+
+### Token introspection
+
+Your API endpoint might receive tokens from users and need to validate the token with ZITADEL.
+In this case your API needs to authenticate with ZITADEL and then do a token introspection.
+Follow our [guide on token introspection with private key JWT](../token-introspection/private-key-jwt) to learn more.
+
+## Call ZITADEL API with PAT
+
+Because the PAT is a ready to use token, you can add it as Authorization Header and send it in your requests to the ZITADEL API.
+In this example we read the organization of the service user.
+
+```bash
+curl --request GET \
+  --url $CUSTOM-DOMAIN/management/v1/orgs/me \
+  --header 'Authorization: Bearer {PAT}' 
+```
+
+
+## Client application authentication
+
+The above steps demonstrate service user authentication.
+If your application also needs to authenticate itself, you can utilize [Client Credentials Grant](./client-credentials).
+Refer to ZITADEL documentation for details on this alternative method.
+
+## Security considerations
+
+* **Store private keys securely:** **Never share or embed the private key in your code or application.** Consider using secure key management solutions.
+* **Set appropriate JWT expiration times:** Limit the validity period of tokens to minimize the impact of potential compromise.
+* **Implement proper error handling:** Handle situations where JWT verification fails or tokens are expired.
+
+By following these steps and adhering to security best practices, you can effectively secure service user and client application communication within ZITADEL using private key JWT authentication.

docs/docs/guides/integrate/service-users/private-key-jwt.md

@@ -0,0 +1,213 @@
+---
+title: Configure private key JWT authentication for service users
+sidebar_label: Private key JWT authentication
+sidebar_position: 2
+---
+
+This guide demonstrates how developers can leverage private key JWT authentication to secure communication between service users and client applications within ZITADEL.
+
+In ZITADEL we use the `urn:ietf:params:oauth:grant-type:jwt-bearer` (**“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523)) authorization grant for this non-interactive authentication.
+
+Read more about the [different authentication methods for service users](authenticate-service-users) and their benefits, drawbacks, and security considerations.
+
+#### How private key JWT authentication works
+
+1. Generate a private/public key pair associated with the service user.
+2. The authorization server stores the public key; and
+3. returns the private key as a json file
+4. The developer configures the client in such a way, that 
+5. JWT assertion is created with the subject of the service user, and the JWT is signed by the private key
+6. Resource owner requests a token by sending the client_assertion
+7. Authorization server validates the signature using the service user's public key
+8. Authorization server returns an OAuth access_token
+9. Resource Owner calls a Resource Server by including the access_token in the Header
+10. Resource Server validates the JWT with [token introspection](../token-introspection/)
+
+![private key jwt authentication sequence diagram](/img/guides/integrate/service-users/sequence-private-key-jwt.svg)
+
+
+## Prerequisites
+
+A code library/framework supporting JWT generation and verification (e.g., `pyjwt` for Python, `jsonwebtoken` for Node.js).
+
+## Steps to authenticate a Service User with private JWT
+
+You need to follow these steps to authenticate a service user and receive an access token that can be used in subsequent requests.
+
+### 1. Create a Service User
+
+1. Navigate to Service Users
+2. Click on **New**
+3. Enter a username and a display name
+4. Click on **Create**
+
+### 2. Generate a private key file
+
+1. Access the ZITADEL web console and navigate to the service user details.
+2. Click on the **Keys** menu point in the detail of your new service user
+3. Click on **New**
+4. You can either set an expiration date or leave it empty if you don't want it to expire
+5. Click on **Download** and save the key file
+
+:::note
+Make sure to save the key file. You won't be able to retrieve it again.
+If you lose it, you will have to generate a new one.
+:::
+
+:::note Expiration
+If you specify an expiration date, note that the key will expire at midnight that day
+:::
+
+![Create private key](/img/console_serviceusers_new_key.gif)
+
+The downloaded JSON should look something like outlined below. The value of `key` contains the _private_ key for your service account. Please make sure to keep this key securely stored and handled with care. The public key is automatically stored in ZITADEL.
+
+```json
+{
+    "type":"serviceaccount",
+    "keyId":"100509901696068329",
+    "key":"-----BEGIN RSA PRIVATE KEY----- [...] -----END RSA PRIVATE KEY-----\n",
+    "userId":"100507859606888466"
+}
+```
+
+### 3. Create a JWT and sign with private key
+
+You need to create a JWT with the following header and payload and sign it with the RS256 algorithm.
+
+Header
+
+```json
+{
+    "alg": "RS256",
+    "kid":"100509901696068329"
+}
+```
+
+Make sure to include `kid` in the header with the value of `keyId` from the downloaded JSON.
+
+Payload
+
+```json
+{
+    "iss": "100507859606888466",
+    "sub": "100507859606888466",
+    "aud": "https://$CUSTOM-DOMAIN",
+    "iat": [Current UTC timestamp, e.g. 1605179982, max. 1 hour ago],
+    "exp": [UTC timestamp, e.g. 1605183582]
+}
+```
+
+* `iss` represents the requesting party, i.e. the owner of the private key. In this case the value of `userId` from the downloaded JSON.
+* `sub` represents the application. Set the value also to the value of `userId`
+* `aud` must be your [Custom Domain](../../../concepts/features/custom-domain)
+* `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) API reference 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.
+
+**Code Example (Python using `pyjwt`):**
+
+```python
+import jwt
+import datetime
+
+# Replace with your service user ID and private key
+service_user_id = "your_service_user_id"
+private_key = "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----"
+
+# ZITADEL API URL (replace if needed)
+api_url = "your_custom_domain"
+
+# Generate JWT claims
+payload = {
+    "iss": "your_zitadel_instance_id",
+    "sub": service_user_id,
+    "aud": api_url,
+    "exp": datetime.utcnow() + datetime.timedelta(minutes=5),
+    "iat": datetime.utcnow()
+}
+
+# Sign the JWT using RS256 algorithm
+encoded_jwt = jwt.encode(payload, private_key, algorithm="RS256")
+
+print(f"Generated JWT: {encoded_jwt}")
+```
+
+### 4. Request an OAuth token with the generated JWT
+
+With the encoded JWT from the prior step, you will need to craft a POST request to ZITADEL's token endpoint:
+
+```bash
+curl --request POST \
+  --url https:/$CUSTOM-DOMAIN/oauth/v2/token \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
+  --data scope='openid' \
+  --data assertion=eyJ0eXAiOiJKV1QiL...
+```
+
+* `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`.
+* `assertion` is the encoded value of the JWT that was signed with your private key from the prior step
+
+If you want to access ZITADEL APIs, make sure to include the required scopes `urn:zitadel:iam:org:project:id:zitadel:aud`.
+Read our guide [how to access ZITADEL APIs](../zitadel-apis/access-zitadel-apis) to learn more.
+
+You should receive a successful response with `access_token`,  `token_type` and time to expiry in seconds as `expires_in`.
+
+```bash
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
+  "token_type": "Bearer",
+  "expires_in": 43199
+}
+```
+
+### 5. Include the access token in the authorization header
+
+When making API requests on behalf of the service user, include the generated token in the "Authorization" header with the "Bearer" prefix.
+
+```bash
+curl --request POST \
+  --url $YOUR_API_ENDOINT \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --header 'Authorization: Bearer MtjHodGy4zxKylDOhg6kW90WeEQs2q...'
+```
+
+## Accessing ZITADEL APIs
+
+You might want to access ZITADEL APIs to manage resources, such as users, or to validate tokens sent to your backend service.
+Follow our guides on [how to access ZITADEL API](../zitadel-apis/access-zitadel-apis) to use the ZITADEL APIs with your service user.
+
+### Token introspection
+
+Your API endpoint might receive tokens from users and need to validate the token with ZITADEL.
+In this case your API needs to authenticate with ZITADEL and then do a token introspection.
+Follow our [guide on token introspection with private key JWT](../token-introspection/private-key-jwt) to learn more.
+
+## Client application authentication
+
+The above steps demonstrate service user authentication.
+If your application also needs to authenticate itself, you can utilize [Client Credentials Grant](./client-credentials).
+Refer to ZITADEL documentation for details on this alternative method.
+
+## Security considerations
+
+* **Store private keys securely:** **Never share or embed the private key in your code or application.** Consider using secure key management solutions.
+* **Set appropriate JWT expiration times:** Limit the validity period of tokens to minimize the impact of potential compromise.
+* **Implement proper error handling:** Handle situations where JWT verification fails or tokens are expired.
+
+By following these steps and adhering to security best practices, you can effectively secure service user and client application communication within ZITADEL using private key JWT authentication.
+
+## Notes
+
+* [JWT with private key](/apis/openidoauth/authn-methods#jwt-with-private-key) API reference
+* [Accessing ZITADEL API](../zitadel-apis/access-zitadel-apis)
+* [Token introspection with private key JWT](../token-introspection/private-key-jwt)

docs/docs/guides/integrate/token-introspection/index.md

@@ -0,0 +1,39 @@
+---
+title: Token introspection
+sidebar_label: Token introspection
+sidebar_position: 1
+---
+
+Token introspection is the process of checking whether an access token is valid and can be used to access protected resources.
+
+You have an API that acts as an OAuth resource server and can be accessed by user-facing applications.
+To validate an access token by calling the ZITADEL introspection API, you can use the JSON Web Token (JWT) Profile (recommended) or Basic Authentication for token introspection.
+It's crucial to understand that the API is entirely separate from the front end.
+The API shouldn’t concern itself with the token type received.
+Instead, it's about how the API chooses to call the introspection endpoint, either through JWT Profile or Basic Authentication.
+Many APIs assume they might receive a JWT and attempt to verify it based on signature or expiration.
+However, with ZITADEL, you can send either a JWT or an opaque Bearer token from the client end to the API.
+This flexibility is one of ZITADEL's standout features.
+
+## API application
+
+If you have an API that behaves as an OAuth resource server that can be accessed by user-facing applications and need to validate an access token by calling the ZITADEL introspection API, you can use the following methods to register these APIs in ZITADEL:
+
+- [JSON Web Token (JWT) Profile (Recommended)](private-key-jwt.mdx)
+- [Basic Authentication](./basic-auth.mdx)
+
+## Service users
+
+If there are client APIs or systems that need to access other protected APIs, these APIs or systems must be declared as [service users](/docs/concepts/structure/users).
+A service user is not considered an application type in ZITADEL.
+Read the introduction on how to [authenticate service users](../service-users/authenticate-service-users.md).
+
+## Further references
+
+- [Introspection API reference](/docs/apis/openidoauth/endpoints#token_endpoint)
+- [JWT vs. opaque tokens](/docs/concepts/knowledge/opaque-tokens.md)
+- [Python examples for securing an API and invoking it as a service user](https://github.com/zitadel/examples-api-access-and-token-introspection)
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />

docs/docs/guides/integrate/token-introspection/private-key-jwt.mdx

@@ -5,7 +5,7 @@ sidebar_label: JSON Web Token(JWT) Profile
 
 import IntrospectionResponse from './_introspection-response.mdx';
 
-This is a guide on how to secure your API using [JSON Web Token (JWT) profile (recommended)](https://zitadel.com/docs/apis/openidoauth/authn-methods#client-secret-basic).  
+This is a guide on how to secure your API using [JSON Web Token (JWT) profile (recommended)](/docs/apis/openidoauth/authn-methods#client-secret-basic).  
 
 ## Register the API in ZITADEL and generate private and public keys 
 

docs/docs/guides/integrate/zitadel-apis/_accessing_zitadel_api.md

@@ -0,0 +1,75 @@
+
+## Accessing ZITADEL APIs
+
+In this step, we will authenticate a service user and receive an access_token to use against the ZITADEL API.
+
+You will need to craft a POST request to ZITADEL's token endpoint:
+
+```bash
+curl --request POST \
+  --url https://$CUSTOM-DOMAIN/oauth/v2/token \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --header 'Authorization: Basic ${BASIC_AUTH}' \
+  --data grant_type=client_credentials \
+  --data scope='openid urn:zitadel:iam:org:project:id:zitadel:aud'
+```
+
+If you want to access the ZITADEL API with this access token, you have to add `urn:zitadel:iam:org:project:id:zitadel:aud` to the list of scopes.
+
+* `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` and `urn:zitadel:iam:org:project:id:zitadel:aud`
+* `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`.
+
+```bash
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
+  "token_type": "Bearer",
+  "expires_in": 43199
+}
+```
+
+
+In this step we will authenticate a service user and receive an access_token to use against the ZITADEL API.
+
+You will need to craft a POST request to ZITADEL's token endpoint:
+
+```bash
+curl --request POST \
+  --url https://$CUSTOM-DOMAIN/oauth/v2/token \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --header 'Authorization: Basic ${BASIC_AUTH}' \
+  --data grant_type=client_credentials \
+  --data scope='openid profile email urn:zitadel:iam:org:project:id:zitadel:aud'
+```
+
+* `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`
+  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`.
+
+```bash
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
+  "token_type": "Bearer",
+  "expires_in": 43199
+}
+```
+
+### Access ZITADEL's API with the token
+
+```bash
+curl --request GET \
+  --url $CUSTOM-DOMAIN/management/v1/orgs/me \
+  --header "Authorization: Bearer $TOKEN" 
+```
+
+Where `$TOKEN` corresponds to the access token from the earlier response.

docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md

@@ -0,0 +1,237 @@
+---
+title: Access ZITADEL APIs
+---
+
+This guide explains what ZITADEL APIs are and how to access ZITADEL APIs using a service user to manage all types of resources and settings.
+
+## What are the ZITADEL APIs
+
+ZITADEL exposes a variety of APIs that allow you to interact with its functionalities programmatically.
+These APIs are offered through different protocols including gRPC and REST.
+Additionally, ZITADEL provides [SDKs for popular languages](/docs/sdk-examples/introduction) and frameworks to simplify integration.
+
+Here's a breakdown of some key points about ZITADEL APIs:
+
+* **Auth API:** Used by authenticated users for tasks related to their accounts.
+* **Management API:** Used by organization managers for administrative tasks.
+* **Admin API:** Used for administrative functions on the ZITADEL instance itself (may require separate user setup).  
+* **System API:** For ZITADEL self-hosted deployments only, providing superordinate control (requires specific configuration).
+
+:::note Resource-based APIs
+ZITADEL is transitioning from a use-case based API structure to a resource-based one, aiming to simplify API usage.
+:::
+
+For further details and in-depth exploration, you can refer to the [ZITADEL API documentation](/docs/apis/introduction).
+
+## How to access ZITADEL APIs
+
+Accessing ZITADEL APIs, except for the Auth API and the System API, requires these basic steps:
+
+1. **Create a service user**: A service user is a special type of account used to grant programmatic access to ZITADEL's functionalities. Unlike regular users who log in with a username and password, [service users rely on a more secure mechanism involving digital keys and tokens](../service-users/authenticate-service-users).
+2. **Give permission to access ZITADEL APIs**: Assign a Manager role to the service user, giving it permission to make changes to certain resources in ZITADEL.
+3. **Authenticate the service user**: Like human users, service users must authenticate and request an OAuth token with the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to access ZITADEL APIs. [Service users can be authenticated](../service-users/authenticate-service-users) using private key JWT, client credentials, or personal access tokens.
+4. **Access ZITADEL APIs with the token**: The OAuth token must be included in the Authorization Header of calls to ZITADEL APIs.
+
+### Accessing Auth API
+
+The Auth API can be used for all operations on the requesting user, meaning the user id in the sub claim of the used token.
+Using this API doesn't require a service user to be authenticated.
+Instead, you call the Auth API with the token of the user.
+
+[Reference documentation for authentication API](/docs/apis/introduction#authentication)
+
+### Accessing System API
+
+With the System API developers can manage different ZITADEL instances.
+The System API can't be accessed by service users and requires a special configuration and authentication that can be found in our [guide to access ZITADEL's System API](./access-zitadel-system-api).
+
+[Reference documentation for system API](/docs/apis/introduction#system)
+
+## 1. Create a service user
+
+First, you need to create a new service user through the console or ZITADEL APIs.
+
+Via Console:
+
+1. In an organization, navigate to Users > Service Users
+2. Click on **New**
+3. Enter a username and a display name
+4. Click on **Create**
+
+Via APIs:
+
+* [Create User (Machine)](/docs/apis/resources/mgmt/management-service-add-machine-user)
+
+## 2. Grant a Manager role to the service user
+
+ZITADEL Managers are Users who have permission to manage ZITADEL itself.
+There are some different levels for managers.
+
+- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole instance.
+- **Org Managers**: Managers in the Organization Level are able to manage everything within the granted Organization.
+- **Project Managers**: At 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)
+
+To be able to access the ZITADEL APIs your service user needs permissions to ZITADEL.
+
+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](/guides/manage/console/managers))
+
+![Add Org Manager](/img/console_org_manager_add.gif)
+
+## 3. Authenticate service user and request token
+
+Service users can be authenticated using private key JWT, client credentials, or personal access tokens.
+The [service user authentication](../service-users/authenticate-service-users) can be used to make machine-to-machine requests to any Resource Server (eg, a backend service / API) by requesting a token from the Authorization Server (ZITADEL) and sending the short-lived token (access token) in the Header of requests.
+
+This guide covers a specific case of service user authentication when requesting access to the [ZITADEL APIs](/docs/apis/introduction).
+While PAT can be used directly to access the ZITADEL APIS, the more secure authentication methods private key JWT and client credentials must include the [reserved scope](/docs/apis/openidoauth/scopes) `urn:zitadel:iam:org:project:id:zitadel:aud` when requesting an access from the token endpoint.
+This scope will add the ZITADEL APIs to the audience of the access token.
+ZITADEL APIs will check if they are in the audience of the access token, and reject the token in case they are not in the audience.
+
+The following sections will explain the more specific authentication to access the ZITADEL APIs.
+
+### Authenticate with private key JWT
+
+Follow the steps in this guide to [generate an key file](../service-users/private-key-jwt#2-generate-a-private-key-file) and [create a JWT and sign with private key](../service-users/private-key-jwt#3-create-a-jwt-and-sign-with-private-key).
+
+With the encoded JWT (assertion) 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 [reserved scope](/apis/openidoauth/scopes) for the audience.
+Use the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to include the ZITADEL project id in your audience
+
+A sample request will look like this
+
+```bash {5}
+curl --request POST \
+  --url $CUSTOM-DOMAIN/oauth/v2/token \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
+  --data scope='openid profile urn:zitadel:iam:org:project:id:zitadel:aud' \
+  --data assertion=eyJ0eXAiOiJKV1QiL...
+```
+
+where 
+
+- `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` and `urn:zitadel:iam:org:project:id:zitadel:aud` to acces the ZITADEL APIs. For this example include `profile`.
+- `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`.
+
+```bash
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
+  "token_type": "Bearer",
+  "expires_in": 43199
+}
+```
+
+Use the access_token in the Authorization header to make requests to the ZITADEL APIs.
+In the following example, we read the organization of the service user.
+
+```bash
+curl --request GET \
+  --url $CUSTOM-DOMAIN/management/v1/orgs/me \
+  --header 'Authorization: Bearer ${TOKEN}' 
+```
+
+### Client credentials
+
+Get the client id and client secret by
+
+1. navigating to the service user, then
+2. Open **Actions** in the top right corner and click on **Generate Client Secret**
+3. Copy the **ClientID** and **ClientSecret** from the dialog
+
+![Create new service user](/img/console_serviceusers_secret.gif)
+
+With the ClientId and ClientSecret from the prior step, you will need to craft a POST request to ZITADEL's token endpoint.
+
+#### Audience scope
+
+**To access the ZITADEL APIs you need the ZITADEL Project ID in the audience of your token.**
+This is possible by sending a [reserved scope](/apis/openidoauth/scopes) for the audience.
+Use the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to include the ZITADEL project id in your audience
+
+In this step we will authenticate a service user and receive an access_token to use against the ZITADEL API.
+
+#### Basic authentication
+
+When using `client_secret_basic` on the token or introspection endpoints, provide an `Authorization` header with a Basic auth value in the following form:
+
+```markdown
+Authorization: "Basic " + base64( formUrlEncode(client_id) + ":" + formUrlEncode(client_secret) )
+```
+
+For an example see the [client secret basic authentication method reference](/docs/apis/openidoauth/authn-methods#client-secret-basic).
+We recommend using an OpenID / OAuth library that handles the encoding for you.
+
+#### Post request
+
+You will need to craft a POST request to ZITADEL's token endpoint:
+
+```bash {6}
+curl --request POST \
+  --url https://$CUSTOM-DOMAIN/oauth/v2/token \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --header 'Authorization: Basic ${BASIC_AUTH}' \
+  --data grant_type=client_credentials \
+  --data scope='openid profile urn:zitadel:iam:org:project:id:zitadel:aud'
+```
+
+where
+
+* `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`
+  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`.
+
+```bash
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
+  "token_type": "Bearer",
+  "expires_in": 43199
+}
+```
+
+Because the received token includes the `urn:zitadel:iam:org:project:id:zitadel:aud` scope, we can send it in your requests to the ZITADEL API as the Authorization Header.
+In this example we read the organization of the service user.
+
+```bash
+curl --request GET \
+  --url $CUSTOM-DOMAIN/management/v1/orgs/me \
+  --header 'Authorization: Bearer ${TOKEN}' 
+```
+
+### Personal access token (PAT)
+
+A Personal Access Token (PAT) is a ready-to-use token which can be used as _Authorization_ header.
+
+Because the PAT is a ready-to-use token, you can add it as Authorization Header and send it in your requests to the ZITADEL API.
+In this example, we read the organization of the service user.
+
+```bash
+curl --request GET \
+  --url $CUSTOM-DOMAIN/management/v1/orgs/me \
+  --header 'Authorization: Bearer {PAT}' 
+```
+
+## Notes
+
+- [Example application in Go](./example-zitadel-api-with-go) to access ZITADEL APIs
+- [Example application in .NET](./example-zitadel-api-with-dot-net) to access ZITADEL APIs
+- Learn how to use the [Event API](./event-api) to retrieve your audit trail
+- Read about the [different methods to authenticate service users](../service-users/authenticate-service-users)

docs/docs/guides/integrate/zitadel-apis/access-zitadel-system-api.md

@@ -1,5 +1,6 @@
 ---
 title: Access ZITADEL System API
+sidebar_label: System API
 ---
 :::note
 This guide focuses on the ZITADEL System API. To access the other APIs (Admin, Auth, Management), please checkout [this guide](./access-zitadel-apis). 

docs/docs/guides/integrate/zitadel-apis/event-api.md

@@ -1,6 +1,6 @@
 ---
 title: Get Events from ZITADEL
-sidebar_label: Events
+sidebar_label: Event API
 ---
 
 ZITADEL leverages the power of eventsourcing, meaning every action and change within the system generates a corresponding event that is stored in the database. 
@@ -9,7 +9,7 @@ This API allows you to easily retrieve and utilize the events generated within t
 
 You need to give a user the [manager role](https://zitadel.com/docs/guides/manage/console/managers) IAM_OWNER_VIEWER or IAM_OWNER to access the Event API.
 
-If you like to know more about eventsourcing/eventstore and how this works in ZITADEL, head over to our [concepts](../../concepts/eventstore/overview).
+If you like to know more about eventsourcing/eventstore and how this works in ZITADEL, head over to our [concepts](/docs/concepts/eventstore/overview).
 ## Request Events
 
 Call the [ListEvents](/apis/resources/admin) enpoint in the Administration API to get all the events you need.

docs/docs/guides/integrate/zitadel-apis/example-zitadel-api-with-dot-net.md

@@ -1,6 +1,6 @@
 ---
-title: Integrate ZITADEL into a .NET Application
+title: Integrate ZITADEL APIs into a .NET Application
-sidebar_label: .NET
+sidebar_label: Example .NET
 ---
 
 This integration guide shows you how to integrate **ZITADEL** into your .NET application.
@@ -15,10 +15,10 @@ If you need any other information about the .NET SDK go to the [documentation](h
 The client [SDK](https://github.com/zitadel/zitadel-net) will handle all necessary OAuth 2.0 requests and send the required headers to the ZITADEL API.
 All that is required, is a service account with an Org Owner (or another role, depending on the needed api requests) role assigned and its key JSON.
 
-However, we recommend you read the guide on [how to access ZITADEL API](../../guides/integrate/access-zitadel-apis) and the associated guides for a basic knowledge of :
+However, we recommend you read the guide on [how to access ZITADEL API](/docs/guides/integrate/zitadel-apis/access-zitadel-apis) and the associated guides for a basic knowledge of :
 
- - [Recommended Authorization Flows](../../guides/integrate/login/oidc/oauth-recommended-flows.md)
+ - [Recommended Authorization Flows](/docs/guides/integrate/login/oidc/oauth-recommended-flows)
- - [Service Users](../../guides/integrate/serviceusers)
+ - [Service Users](/docs/guides/integrate/service-users/authenticate-service-users)
 
 > Be sure to have a valid key JSON and that its service account is either ORG_OWNER or at least ORG_OWNER_VIEWER before you continue with this guide.
 

docs/docs/guides/integrate/zitadel-apis/example-zitadel-api-with-go.md

@@ -1,6 +1,6 @@
 ---
-title: Integrate ZITADEL into a Go Application
+title: Integrate ZITADEL APIs into a Go Application
-sidebar_label: Go
+sidebar_label: Example Go
 ---
 
 This integration guide shows you how to integrate **ZITADEL** into your Go application.
@@ -15,9 +15,9 @@ At the end of the guide you should have an application able to read the details
 The client [SDK](https://github.com/zitadel/zitadel-go) will handle all necessary OAuth 2.0 requests and send the required headers to the ZITADEL API using our [OIDC client library](https://github.com/zitadel/oidc).
 All that is required, is a service account with an Org Owner (or another role, depending on the needed api requests) role assigned and its key JSON.
 
-However, we recommend you read the guide on [how to access ZITADEL API](../../guides/integrate/access-zitadel-apis) and the associated guides for a basic knowledge of :
+However, we recommend you read the guide on [how to access ZITADEL API](/docs/guides/integrate/zitadel-apis/access-zitadel-apis)) and the associated guides for a basic knowledge of :
- - [Recommended Authorization Flows](../../guides/integrate/login/oidc/oauth-recommended-flows.md)
+ - [Recommended Authorization Flows](/docs/guides/integrate/login/oidc/oauth-recommended-flows)
- - [Service Users](../../guides/integrate/serviceusers)
+ - [Service Users](/docs/guides/integrate/service-users/authenticate-service-users)
 
 > Be sure to have a valid key JSON and that its service account is either ORG_OWNER or at least ORG_OWNER_VIEWER before you continue with this guide.
 

docs/docs/guides/manage/terraform/basics.md

@@ -10,7 +10,7 @@ It covers how to:
 Prerequisites:
 
 - A ZITADEL Instance, if not present follow [this guide](../../start/quickstart)
-- A user with enough authorization to manage the desired resources, if not present follow [this guide](../../integrate/serviceusers)
+- A user with enough authorization to manage the desired resources, if not present follow [this guide](/docs/guides/integrate/service-users/authenticate-service-users)
 - Installed Terraform, if not present follow [this guide](https://learn.hashicorp.com/tutorials/terraform/install-cli)
 
 ## Manage ZITADEL resources through terraform

docs/docs/guides/migrate/sources/keycloak.md

@@ -97,7 +97,7 @@ As explained in this [ZITADEL user migration guide](https://zitadel.com/docs/gui
 
 ### Create a service user to consume ZITADEL API
 
-But first of all, in order to use this ZITADEL API, you need to create a [service user](https://zitadel.com/docs/guides/integrate/serviceusers#exercise-create-a-service-user). 
+But first of all, in order to use this ZITADEL API, you need to create a [service user](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users#exercise-create-a-service-user). 
 
 Go to the **Users** menu and select the **Service Users** tab. And click the **+ New** button. 
 
@@ -113,7 +113,7 @@ Your service user is now created and listed.
 
 ### Provide 'Org Owner' permissions to the service user
 
-This service user needs to have elevated permissions in order to import users. For this example, you should make the service user an organization owner as explained in [this guide](https://zitadel.com/docs/guides/integrate/access-zitadel-apis#add-org_owner-to-service-user). 
+This service user needs to have elevated permissions in order to import users. For this example, you should make the service user an organization owner as explained in [this guide](/docs/guides/integrate/zitadel-apis/access-zitadel-apis#add-org_owner-to-service-user). 
 
 Let's change the permissions as follows: 
 
@@ -127,7 +127,7 @@ Next, select your service user that you created and select the **Org Owner** che
 
 ### Generate an access token for the service user
 
-In order for the service user to access the API, they must be able to authenticate themselves. To authenticate the user, you can use either [JWT with Private Key](/docs/guides/integrate/serviceusers#authenticating-a-service-user) flow (recommended for production) or [Personal Access Tokens](/docs/guides/integrate/pat)(PAT). In this guide, we will choose the latter. 
+In order for the service user to access the API, they must be able to authenticate themselves. To authenticate the user, you can use either [JWT with Private Key](/docs/guides/integrate/service-users/authenticate-service-users#authenticating-a-service-user) flow (recommended for production) or [Personal Access Tokens](/docs/guides/integrate/service-users/personal-access-token)(PAT). In this guide, we will choose the latter. 
 
 Go to **Users** -> **Service Users** again and click on the service user, then select **Personal Access Tokens** on the left and click the **+ New** button. Copy the generated personal access token to use it later.  Click **Close** after copying the PAT. 
 

docs/docs/guides/migrate/sources/zitadel.md

@@ -36,7 +36,7 @@ You need a PAT from a service user with IAM Owner permissions in both the source
 
 1. Go to your default organization
 2. Create a service user "import_user" with Access Token Type "Bearer"
-3. Create a [personal access token](/docs/guides/integrate/pat)
+3. Create a [personal access token](/docs/guides/integrate/service-users/personal-access-token)
 4. Go to the global instance settings
 5. Add the import_user as [manager](/docs/guides/manage/console/managers) with the role "IAM Owner"
 
@@ -46,7 +46,7 @@ Save the PAT to the environment variabel `PAT_EXPORT_TOKEN` and the source domai
 
 1. Go to your default organization
 2. Create a service user "export_user" with Access Token Type "Bearer"
-3. Create a [personal access token](/docs/guides/integrate/pat)
+3. Create a [personal access token](/docs/guides/integrate/service-users/personal-access-token)
 4. Go to the global instance settings
 5. Add the export_user as [manager](/docs/guides/manage/console/managers) with the role "IAM Owner"
 

docs/docs/guides/solution-scenarios/restrict-console.mdx

@@ -53,7 +53,7 @@ First you need a user with manager permissions to change the project settings in
 This means either you add the manager to the organization or you use a manager on the instance level with "IAM-OWNER" permissions.
 After that create a Personal Access Token (PAT) for the manager.
 
-More detailed information about creating a PAT and manager roles you can find [here](/docs/guides/integrate/pat)
+More detailed information about creating a PAT and manager roles you can find [here](/docs/guides/integrate/service-users/personal-access-token)
 
 Then you have to send the following request:
 ```bash

docs/docs/imports/_code-flow-chart.md

@@ -5,7 +5,7 @@ sequenceDiagram
     participant App
     participant AS as Authorization Server (ZITADEL)
     RO-->>App: Open App
-    App->>AS: Authorization Rrequest to /authorize
+    App->>AS: Authorization Request to /authorize
     AS->>RO: redirect to login
     RO->>AS: user authentication
     AS->>App: authorization code response

docs/docs/self-hosting/manage/usage_control.md

@@ -31,7 +31,7 @@ DefaultInstance:
 
 You can restrict the maximum age of events returned by the following APIs:
 
-- [Events Search](/apis/resources/admin/admin-service-list-events), See also the [Event API guide](/guides/integrate/event-api)
+- [Events Search](/apis/resources/admin/admin-service-list-events), See also the [Event API guide](/guides/integrate/zitadel-apis/event-api)
 - [My User History](/apis/resources/auth/auth-service-list-my-user-changes)
 - [A Users History](/apis/resources/mgmt/management-service-list-user-changes)
 - [An Applications History](/apis/resources/mgmt/management-service-list-app-changes)

docs/docs/support/advisory/a10007.md

@@ -14,7 +14,7 @@ This advisory applies to self-hosted ZITADEL installations with custom roles to
 
 ## Description
 
-In upcoming ZITADEL versions, RBAC also applies to [system users defined in the ZITADEL runtime configuration](/guides/integrate/access-zitadel-system-api#runtime-configuration).
+In upcoming ZITADEL versions, RBAC also applies to [system users defined in the ZITADEL runtime configuration](/docs/guides/integrate/zitadel-apis/access-zitadel-system-api#runtime-configuration).
 This enables fine grained access control to the system API as well as other APIs for system users.
 ZITADEL defines the new default roles *SYSTEM_OWNER* and *SYSTEM_OWNER_VIEWER*.
 System users without any memberships defined in the configuration will be assigned the *SYSTEM_OWNER* role.

docs/sidebars.js

@@ -205,10 +205,10 @@ module.exports = {
           label: "Login Users",
           link: {
             type: "generated-index",
-            title: "Integrate",
+            title: "Login users with ZITADEL",
             slug: "guides/integrate/login",
             description:
-              "Integrate your users and application with ZITADEL. In this section you will find resource on how to authenticate your users, configure external identity providers, access the ZITADEL APIs to manage resources, and integrate with third party services and tools.",
+              "Sign-in users and application with ZITADEL. In this section you will find resources on how to authenticate your users by using the hosted login via OpenID Connect and SAML. Follow our dedicated guides to build your custom login user interface, if you want to customize the login behavior further.",
           },
           items: [
             "guides/integrate/login/login-users",
@@ -270,34 +270,27 @@ module.exports = {
         {
           type: "category",
           label: "Token Introspection",
-          link: {
-            type: "generated-index",
-            title: "Token Introspection",
-            slug: "/guides/integrate/token-introspection",
-            description:
-              "Token introspection is the process of checking whether an access token is valid and can be used to access protected resources. You have an API that acts as an OAuth resource server and can be accessed by user-facing applications. To validate an access token by calling the ZITADEL introspection API, you can use the JSON Web Token (JWT) Profile (recommended) or Basic Authentication for token introspection. It's crucial to understand that the API is entirely separate from the front end. The API shouldn’t concern itself with the token type received. Instead, it's about how the API chooses to call the introspection endpoint, either through JWT Profile or Basic Authentication. Many APIs assume they might receive a JWT and attempt to verify it based on signature or expiration. However, with ZITADEL, you can send either a JWT or an opaque Bearer token from the client end to the API. This flexibility is one of ZITADEL's standout features.",
-          },
           collapsed: true,
           items: [
-            "guides/integrate/token-introspection/private-key-jwt",
+            {
-            "guides/integrate/token-introspection/basic-auth",
+              type: "autogenerated",
+              dirName: "guides/integrate/token-introspection",
+            },
           ],
         },
         {
           type: "category",
-          label: "Authenticate Service Users",
+          label: "Service Users",
           link: {
-            type: "generated-index",
+            type: "doc",
-            title: "Authenticate ZITADEL Service Users",
+            id: "guides/integrate/service-users/authenticate-service-users"
-            slug: "/guides/integrate/serviceusers",
-            description:
-              "How to authenticate service users for machine-to-machine (M2M) communication between services. You also need to authenticate service users to access ZITADEL's APIs.",
           },
           collapsed: true,
           items: [
-            "guides/integrate/private-key-jwt",
+            {
-            "guides/integrate/client-credentials",
+              type: "autogenerated",
-            "guides/integrate/pat",
+              dirName: "guides/integrate/service-users",
+            },
           ],
         },
         {
@@ -362,25 +355,16 @@ module.exports = {
         },
         {
           type: "category",
-          label: "Access ZITADEL APIs",
+          label: "ZITADEL APIs",
+          link: {
+            type: "doc",
+            id: "guides/integrate/zitadel-apis/access-zitadel-apis"
+          },
           collapsed: true,
           items: [
             {
-              type: "link",
+              type: "autogenerated",
-              label: "Authenticate Service Users",
+              dirName: "guides/integrate/zitadel-apis",
-              href: "/guides/integrate/serviceusers",
-            },
-            "guides/integrate/access-zitadel-apis",
-            "guides/integrate/access-zitadel-system-api",
-            "guides/integrate/event-api",
-            {
-              type: "category",
-              label: "Example Code",
-              items: [
-                "examples/call-zitadel-api/go",
-                "examples/call-zitadel-api/dot-net",
-              ],
-              collapsed: true,
             },
           ],
         },
@@ -540,11 +524,6 @@ module.exports = {
       items: [
         "support/software-release-cycles-support",
         "support/troubleshooting",
-        {
-          type: "link",
-          label: "Support Service Descriptions",
-          href: "/legal/service-description/support-services",
-        },
         {
           type: "category",
           label: "Technical Advisory",

docs/vercel.json

@@ -29,6 +29,15 @@
         { "source": "/docs/guides/solution-scenarios/onboarding/b2b", "destination": "/docs/guides/integrate/onboarding/b2b", "permanent": true },
         { "source": "/docs/guides/solution-scenarios/onboarding/end-users", "destination": "/docs/guides/integrate/onboarding/end-users", "permanent": true },
         { "source": "/docs/concepts/structure/jwt_idp", "destination": "/docs/guides/integrate/identity-providers/jwt-idp", "permanent": true },
-        { "source": "/docs/concepts/structure/jwt-idp", "destination": "/docs/guides/integrate/identity-providers/jwt-idp", "permanent": true }
+        { "source": "/docs/guides/solution-scenarios/onboarding/end-users", "destination": "/docs/guides/integrate/onboarding/end-users", "permanent": true },
+        { "source": "/docs/guides/integrate/serviceusers", "destination": "/docs/guides/integrate/service-users/authenticate-service-users", "permanent": true },
+        { "source": "/docs/guides/integrate/private-key-jwt", "destination": "/docs/guides/integrate/service-users/private-key-jwt", "permanent": true },
+        { "source": "/docs/guides/integrate/client-credentials", "destination": "/docs/guides/integrate/service-users/client-credentials", "permanent": true },
+        { "source": "/docs/guides/integrate/pat", "destination": "/docs/guides/integrate/service-users/private-access-token", "permanent": true },
+        { "source": "/docs/guides/integrate/access-zitadel-apis", "destination": "/docs/guides/integrate/zitadel-apis/access-zitadel-apis", "permanent": true },
+        { "source": "/docs/guides/integrate/access-zitadel-system-api", "destination": "/docs/guides/integrate/zitadel-apis/access-zitadel-system-api", "permanent": true },
+        { "source": "/docs/guides/integrate/event-api", "destination": "/docs/guides/integrate/zitadel-apis/event-api", "permanent": true },
+        { "source": "/docs/examples/call-zitadel-api/go", "destination": "/docs/guides/integrate/zitadel-apis/example-zitadel-api-with-go", "permanent": true },
+        { "source": "/docs/examples/call-zitadel-api/dot-net", "destination": "/docs/guides/integrate/zitadel-apis/example-zitadel-api-with-dot-net", "permanent": true }
     ]
 }