docs: Add note for updated terminology (#11802)

# Which Problems Are Solved

For existing customers it could be hard to understand the new aligned
terms we have defined, if they are already used to the "old term"

# How the Problems Are Solved

Adding notes at the top of docs pages to state clearliy new and old
terms.
This commit is contained in:
Fabienne Bühler
2026-03-16 09:10:48 +00:00
committed by GitHub
parent cadf75e4fe
commit 9a4530bf77
15 changed files with 169 additions and 90 deletions
@@ -3,6 +3,12 @@ title: External User Role Assignments
description: "Grant access to projects for external users from other organizations using ZITADEL's external user role assignments"
---
<TerminologyUpdate
newTerm="Role Assignment"
oldTerms={["User Grant", "Authorization"]}
/>
ZITADEL's external user role assignment is a feature that allows you to grant access to projects within your organization to users from other organizations.
This is useful in scenarios where you want to collaborate with external users without needing them to be part of your organization.
By using external user role assignments, you can streamline collaboration with external users while maintaining control over access to your projects within ZITADEL.
@@ -6,6 +6,12 @@ sidebar_label: Administrators
import AdministratorDescription from "./_administrator_description.mdx";
<TerminologyUpdate
newTerm="Administrators"
oldTerms={["Members", "Memberships", "Managers"]}
/>
<AdministratorDescription components={props.components} name="AdministratorDescription" />
Notes:
@@ -4,6 +4,11 @@ description: "Overview of ZITADEL Instances—the virtual tenants providing full
sidebar_label: Instances
---
<TerminologyUpdate
newTerm="Instance"
oldTerms={["IAM"]}
/>
## Instance Structure
An instance is the top node in ZITADEL's data hierarchy.
@@ -4,6 +4,11 @@ description: "Methods for retrieving assigned user roles and authorizations for
sidebar_label: Retrieve User Roles
---
<TerminologyUpdate
newTerm="Role Assignment"
oldTerms={["User Grant", "Authorization"]}
/>
This guide explains all the possible ways of retrieving user roles across different organizations and projects using ZITADEL's APIs.
## What are roles and role assignments in ZITADEL?
@@ -6,6 +6,11 @@ sidebar_label: Authenticate service accounts
import DocCardList from '@/components/docusaurus/doc-card-list';
<TerminologyUpdate
newTerm="Service Accounts"
oldTerms={["Service User", "Machine Users", "Technical Account"]}
/>
This guide explains ZITADEL service accounts and their role in facilitating secure machine-to-machine communication within your applications.
## What are Service Accounts?
@@ -9,6 +9,11 @@ import AddAdministrator from "./_add_administrator.mdx";
import PermissionTable from '@/components/PermissionTable';
import permissionData from "../../../../../../cmd/defaults.yaml";
<TerminologyUpdate
newTerm="Administrators"
oldTerms={["Members", "Memberships", "Managers"]}
/>
<AdministratorDescription components={props.components} name="AdministratorDescription" />
To configure administrators in ZITADEL, go to the resource where you like to add it (e.g., Instance, Organization, Project, GrantedProject).
@@ -4,6 +4,11 @@ description: "Define custom roles and manage user role assignments within your Z
sidebar_label: Roles and Role Assignments
---
<TerminologyUpdate
newTerm="Role Assignment"
oldTerms={["User Grant", "Authorization"]}
/>
If you built out the [POS use case example](./projects-overview#example-scenario), you would probably need an application for administration.
In this application you would probably have somebody accessing as an accountant and somebody as an administrator, who is somebody with enhanced rights.
To achieve this, you would have to add this distinction as roles.
@@ -24,6 +24,12 @@ Users represent actual people who log in via an interactive interface (e.g., a l
Read more on how to [login users with ZITADEL](/guides/integrate/login/login-users).
### Service Accounts
<TerminologyUpdate
newTerm="Service Accounts"
oldTerms={["Service User", "Machine Users", "Technical Account"]}
/>
Service accounts represent machines, backend services, or IoT devices requiring non-interactive access.
* **Profile:** Only has a name, description, and username.
* **Authentication:** Authenticates via **JWT Profile** or **Personal Access Tokens (PAT)**. Both methods support expiration settings.