chore: rename IAM to instance (#11351)

# Which Problems Are Solved In many cases IAM was used where instance was meant. # How the Problems Are Solved - Rename wrong usage of IAM to instance all over the code base. - Add an agents.md which explains the terms used in Zitadel's architecture. # Additional Context - closes #11280 --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: muhlemmer <[email protected]> Co-authored-by: Copilot <[email protected]> Co-authored-by: Marco A. <[email protected]>
2026-11-04 05:12:16 +00:00 · 2026-02-10 20:25:39 +01:00
parent 67a02a6aeb
commit 5a2181bcec
110 changed files with 392 additions and 478 deletions
@@ -111,7 +111,7 @@ API Reference:

 ### Management

-The management API is as the name states the interface where systems can mutate IAM objects like, organizations, projects, applications, users and so on if they have the necessary access rights.
+The management API is as the name states the interface where systems can mutate instance objects like, organizations, projects, applications, users and so on if they have the necessary access rights.
 To identify the current organization you can send a header `x-zitadel-orgid` or if no header is set, the organization of the authenticated user is set.

 </div>
@@ -3,7 +3,7 @@ title: Scopes in ZITADEL
 sidebar_label: Scopes
 ---

-ZITADEL supports the usage of scopes as way of requesting information from the IAM and also instruct ZITADEL to do certain operations.
+ZITADEL supports the usage of scopes as way of requesting information from the instance and also instruct ZITADEL to do certain operations.

 ## Standard Scopes

@@ -3,9 +3,9 @@ title: SCIM v2.0 (Preview)
 ---

 The Zitadel [SCIM v2](https://scim.cloud/) service provider interface enables seamless integration of identity and
-access management (IAM) systems with Zitadel,
+access management (instance) systems with Zitadel,
 following the System for Cross-domain Identity Management (SCIM) v2.0 specification.
-This interface allows standardized management of IAM resources, making it easier to automate user provisioning and
+This interface allows standardized management of instance resources, making it easier to automate user provisioning and
 deprovisioning.

 ## Supported endpoints
@@ -31,7 +31,7 @@ Simply steer traffic by path, hostname, IP address or any other metadata to the

 ### Single Cluster / Region

-A Zitadel Cluster is a highly available IAM system with each component critical for serving traffic laid out at least three times.
+A Zitadel Cluster is a highly available instance system with each component critical for serving traffic laid out at least three times.
 Our storage layer (Postgres) is built for single region deployments.
 Hence our reference design for Kubernetes is to have three application nodes and one storage node.

@@ -1,7 +1,7 @@
 ZITADEL is organized around the idea that:

 * Multiple organizations can be managed within one [instance](/concepts/structure/instance).
-* organizations can grant each other rights to self-manage certain aspects of the IAM (eg, roles for access management)
+* organizations can grant each other rights to self-manage certain aspects of the instance (eg, roles for access management)
 * organizations are vessels for users and projects

 ![](../../../public/img/concepts/objects/organization.png)
@@ -433,7 +433,7 @@ This gives us a response with the ID token in the `access_token` field and the `
 With impersonation we can let one user assume the role of another user.

 <Callout>
-Currently impersonated tokens cannot be used for the ZITADEL API. This is to prevent privilege escalation where a impersonator could become an IAM owner, for example. We might enable the use of impersonated tokens in the future.
+Currently impersonated tokens cannot be used for the ZITADEL API. This is to prevent privilege escalation where a impersonator could become an instance owner, for example. We might enable the use of impersonated tokens in the future.
 </Callout>

 ### Preparation
@@ -452,8 +452,8 @@ Next we need to configure which users are allowed to impersonate other users. ZI

 | Name                   | Role                      | Description                                                       |
 | ---------------------- | ------------------------- | ----------------------------------------------------------------- |
-| IAM Admin Impersonator | IAM_ADMIN_IMPERSONATOR    | Allow impersonation of admin and end users from all organizations |
-| IAM Impersonator       | IAM_END_USER_IMPERSONATOR | Allow impersonation of end users from all organizations           |
+| Instance Admin Impersonator | IAM_ADMIN_IMPERSONATOR    | Allow impersonation of admin and end users from all organizations |
+| Instance Impersonator       | IAM_END_USER_IMPERSONATOR | Allow impersonation of end users from all organizations           |
 | Org Admin Impersonator | ORG_ADMIN_IMPERSONATOR    | Allow impersonation of admin and end users from the organization  |
 | Org Impersonator       | ORG_END_USER_IMPERSONATOR | Allow impersonation of end users from the organization            |

@@ -65,7 +65,7 @@ Via APIs23: * [Create User (Machine)](/reference/api/management/zitadel.manageme
 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 Administrator roles are able to manage the whole instance.
+- **Instance Managers**: This is the highest level. Users with IAM Administrator 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.
@@ -21,13 +21,13 @@ In the right part of the management console you can find **MANAGERS** in the det

 | Name                          | Role                          | Description                                                                                                  |
 | ----------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| IAM Owner                     | IAM_OWNER                     | Manage the IAM, manage all organizations with their content                                                  |
-| IAM Owner Viewer              | IAM_OWNER_VIEWER              | View the IAM and view all organizations with their content                                                   |
-| IAM Org Manager               | IAM_ORG_MANAGER               | Manage all organizations including their policies, projects and users                                        |
-| IAM User Manager              | IAM_USER_MANAGER              | Manage all users and their authorizations over all organizations                                             |
-| IAM Admin Impersonator        | IAM_ADMIN_IMPERSONATOR        | Allow impersonation of admin and end users from all organizations                                            |
-| IAM Impersonator              | IAM_END_USER_IMPERSONATOR     | Allow impersonation of end users from all organizations                                                      |
-| IAM Login Client              | IAM_LOGIN_CLIENT              | Get all permissions needed to implement your own Login UI.                                                    |
+| Instance Owner                | IAM_OWNER                     | Manage the Instance, manage all organizations with their content                                             |
+| Instance Owner Viewer         | IAM_OWNER_VIEWER              | View the Instance and view all organizations with their content                                              |
+| Instance Org Manager          | IAM_ORG_MANAGER               | Manage all organizations including their policies, projects and users                                        |
+| Instance User Manager         | IAM_USER_MANAGER              | Manage all users and their authorizations over all organizations                                             |
+| Instance Admin Impersonator   | IAM_ADMIN_IMPERSONATOR        | Allow impersonation of admin and end users from all organizations                                            |
+| Instance Impersonator         | IAM_END_USER_IMPERSONATOR     | Allow impersonation of end users from all organizations                                                      |
+| Instance Login Client         | IAM_LOGIN_CLIENT              | Get all permissions needed to implement your own Login UI.                                                   |
 | Org Owner                     | ORG_OWNER                     | Manage everything within an organization                                                                     |
 | Org Owner Viewer              | ORG_OWNER_VIEWER              | View everything within an organization                                                                       |
 | Org User Manager              | ORG_USER_MANAGER              | Manage users and their authorizations within an organization                                                 |
@@ -2,7 +2,7 @@
 title: SCIM v2.0
 ---

-Zitadel’s **[SCIM v2](https://scim.cloud/) service provider interface** enables standardized provisioning and lifecycle management of users and other IAM resources.
+Zitadel’s **[SCIM v2](https://scim.cloud/) service provider interface** enables standardized provisioning and lifecycle management of users and other instance resources.
 By implementing the official *System for Cross-domain Identity Management (SCIM) v2.0* specification, Zitadel allows seamless and automated user creation, updates, deactivation, and deprovisioning across systems.

 ## API
@@ -14,7 +14,7 @@ This guide explains how to migrate from ZITADEL, this includes
 The following scripts don't include:

 - Global policies
- IAM members
+- Instance members
 - Global IDPs
 - Global second factor / multi-factors
 - Machine keys
@@ -30,7 +30,7 @@ Note that the resources will be migrated without the event stream. This means th

 ## Authorization

-You need a PAT from a service user with IAM Owner permissions in both the source and target system.
+You need a PAT from a service user with instance Owner permissions in both the source and target system.

 ### Source system

@@ -38,7 +38,7 @@ You need a PAT from a service user with IAM Owner permissions in both the source
 2. Create a service user "import_user" with Access Token Type "Bearer"
 3. Create a [personal access token](/guides/integrate/service-accounts/personal-access-token)
 4. Go to the Default settings
-5. Add the import_user as [manager](/guides/manage/console/managers) with the role "IAM Owner"
+5. Add the import_user as [manager](/guides/manage/console/managers) with the role "instance Owner"

 Save the PAT to the environment variable `PAT_EXPORT_TOKEN` and the source domain as `ZITADEL_EXPORT_DOMAIN` to run the following scripts.

@@ -48,7 +48,7 @@ Save the PAT to the environment variable `PAT_EXPORT_TOKEN` and the source domai
 2. Create a service user "export_user" with Access Token Type "Bearer"
 3. Create a [personal access token](/guides/integrate/service-accounts/personal-access-token)
 4. Go to the Default settings
-5. Add the export_user as [manager](/guides/manage/console/managers) with the role "IAM Owner"
+5. Add the export_user as [manager](/guides/manage/console/managers) with the role "instance Owner"

 Save the PAT to the environment variable `PAT_IMPORT_TOKEN` and the source domain as `ZITADEL_IMPORT_DOMAIN` to run the following scripts.

@@ -171,7 +171,7 @@ Topics of the onboarding term may include
 <Tabs>
    <Tab value="in" label="Topics in scope">
      <ul>
-        <li>IAM Configuration</li>
+        <li>Instance Configuration</li>
        <li>Walk-though all features</li>
        <li>Users / Manuals</li>
        <li>Authentication & Management APIs</li>
@@ -68,7 +68,7 @@ To use private information — such as a database admin credential — without s

 All configuration properties are configurable using environment variables.
 ZITADEL environment variable keys are prefixed with `ZITADEL_`.
-For example, to configure the default ZITADEL IAM admin username and password set the `zitadel` binary runtime environment variables `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME` and `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD`.
+For example, to configure the default ZITADEL instance admin username and password set the `zitadel` binary runtime environment variables `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME` and `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD`.
 All supported environment variables are listed in the [runtime configuration file](#runtime-configuration-file) and the [database initialization file](#database-initialization-file).

 ### Proxy configuration
@@ -17,7 +17,7 @@ In the following URLs, replace the base URL and the user ID according to your en
 1. Create a new machine user, for example at http://localhost:8080/ui/console/users/create-machine
 2. Create a PAT, for example at http://localhost:8080/ui/console/users/332169800719532035?new=true&id=pat
 3. Save the PAT to a file, for example `/path/on/your/host/login-client.pat`
-4. Make sure the user has the `Iam Login Client` role (internally called `IAM_LOGIN_CLIENT`), for example at http://localhost:8080/ui/console/instance/members
+4. Make sure the user has the `Instance Login Client` role (internally called `IAM_LOGIN_CLIENT`), for example at http://localhost:8080/ui/console/instance/members

 # Configure the Login UI

@@ -32,9 +32,9 @@ docker run -p 3000:3000 -v /path/on/your/host/login-client.pat:/path/in/containe
 # Enable the Login UI for all users

 <Callout type="warn">
-Before doing this, make sure you have a working PAT for an Iam Owner user.
+Before doing this, make sure you have a working PAT for an instance Owner user.
 In case something goes wrong and you lock yourself out from the login screen, you can revert the changes.
-Create a machine user PAT like you created the [login client PAT above](#create-login-client), but give the user the Iam Owner role (internally called `IAM_OWNER`).
+Create a machine user PAT like you created the [login client PAT above](#create-login-client), but give the user the instance Owner role (internally called `IAM_OWNER`).
 </Callout>

 Enable the `Login V2` feature flag, for example at the bottom of http://localhost:8080/ui/console/instance?id=features.
@@ -78,7 +78,7 @@ services:
      # Set up a service account with IAM_LOGIN_CLIENT role and write the PAT to the file ./login-client.pat
      ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH: /current-dir/login-client.pat
      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_USERNAME: login-client
-      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME: Automatically Initialized IAM Login Client
+      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME: Automatically Initialized instance Login Client
      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_EXPIRATIONDATE: '2029-01-01T00:00:00Z'
      # The master key is used to
    networks: