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
@@ -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.