chore: rename manager/member to administrator (#11542)

# Which Problems Are Solved

As part of the naming consistency initiative, the terms `Manager`,
`Member` and other similar terms that are used in the context of an
administrator are replaced by `Administrator` in the UI and
documentation.

# How the Problems Are Solved

By replacing the following terms with Administrator / Administrator
Roles in docs, Console UI, and guides.

- Manager
- Add Manager
- Add a Manager
- Administrator (used as a person type)
- Membership
- Member grants

# Additional Changes
minor grammatical edits in the docs

# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/11291

---------

Co-authored-by: Marco A. <[email protected]>
This commit is contained in:
Gayathri Vijayan
2026-02-11 17:43:06 +01:00
committed by GitHub
co-authored by Marco A.
parent 319c466476
commit cc7a6145f1
77 changed files with 832 additions and 833 deletions
@@ -10,7 +10,7 @@ This is useful for integrating with other systems or for triggering workflows ba
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
- Your ZITADEL instance needs to have the actions feature enabled.
<Callout>
@@ -10,7 +10,7 @@ This is useful for integrating with other systems which need specific claims in
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
- Your ZITADEL instance needs to have the actions feature enabled.
<Callout>
@@ -10,7 +10,7 @@ This is useful for integrating with other systems which need specific claims in
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
- Your ZITADEL instance needs to have the actions feature enabled.
<Callout>
@@ -10,7 +10,7 @@ This is useful for adding information to managed resources in ZITADEL.
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
- Your ZITADEL instance needs to have the actions feature enabled.
<Callout>
@@ -15,7 +15,7 @@ The examples are based on the request action, but the same principles apply to o
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
<Callout type="info">
Note that this guide assumes that ZITADEL is running on the same machine as the target and can be reached via `localhost`.
@@ -10,7 +10,7 @@ This is useful for information provisioning in between systems or for triggering
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
- Your ZITADEL instance needs to have the actions feature enabled.
<Callout>
@@ -10,7 +10,7 @@ This is useful for triggering workflows based on API responses in ZITADEL. You c
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
- Your ZITADEL instance needs to have the actions feature enabled.
<Callout>
@@ -10,7 +10,7 @@ This is useful for information provisioning in between systems or for triggering
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/managers)
- You need to be at least a ZITADEL [_IAM_OWNER_](/guides/manage/console/administrators)
- Your ZITADEL instance needs to have the actions feature enabled.
<Callout>
@@ -3,15 +3,15 @@ When your user is done using your application and clicks on the logout button, y
Sessions can be terminated by either:
- the authenticated user
- a manager, who is granted `session.delete` (e.g. ORG_OWNER) on the authenticated users organisation
- an administrator, who is granted `session.delete` (e.g. ORG_OWNER) on the authenticated users organization
- providing the current session_token in the body.
Terminating a session means to delete it.
If you try to read or update the session afterward, you will get an error that the Session does not exist or was terminated.
### Request for authenticated users or managers
### Request for authenticated users or administrators
Make sure that the provided token is from the authenticated user, resp. the manager:
Make sure that the provided token is from the authenticated user, resp. the administrator:
```bash
curl --request DELETE \
@@ -37,7 +37,7 @@ Overall, ZITADEL's hosted login page simplifies the authentication process for d
Different login name formats can be used on ZITADEL's hosted login page to select a user.
Login methods can be a user's username, containing the username and an [organization domain](/guides/manage/console/organizations-overview#usernames-and-domains), their email addresses, or their phone numbers.
By default, all of these login methods are allowed and can be adjusted by [Managers](/concepts/structure/managers) to meet their requirements.
By default, all of these login methods are allowed and can be adjusted by [Administrators](/concepts/structure/administrators) to meet their requirements.
### Support for multiple authentication methods
@@ -62,9 +62,9 @@ ZITADEL simplifies multi-tenancy authentication by securely managing authenticat
Key features include:
1. **Secure Tenant Isolation**: Ensures robust security measures to prevent unauthorized access between tenants, maintaining data privacy and compliance. [Managers](/concepts/structure/managers) for an organization have only access to data and configuration within their Organization.
1. **Secure Tenant Isolation**: Ensures robust security measures to prevent unauthorized access between tenants, maintaining data privacy and compliance. [Administrators](/concepts/structure/administrators) for an organization have only access to data and configuration within their Organization.
2. **Custom Authentication Configurations**: Allows tailored [authentication settings](/guides/manage/console/default-settings#login-behavior-and-access), [branding](/guides/manage/customize/branding), and policies for each tenant.
3. **Centralized Management**: Provides [centralized administration](/guides/manage/console/managers) for efficient management across all tenants.
3. **Centralized Management**: Provides [centralized administration](/guides/manage/console/administrators) for efficient management across all tenants.
4. **Scalability and Flexibility**: Scales seamlessly to accommodate growing organizations of all sizes.
5. **Domain Discovery**: Starting on a central login page, route users to their tenant based on their email address or other user attributes. Authentication settings will be applied automatically based on the organization's policies, this includes routing users seamlessly to third party identity providers like [Entra ID](/guides/integrate/identity-providers/azure-ad-oidc).
@@ -180,7 +180,7 @@ You can also activate the v2 login for your apps, so users are redirected to `/u
1. [Create a service user](/guides/integrate/service-accounts/personal-access-token#create-a-service-user-with-a-pat) with a PAT in your instance
2. Give the user IAM_LOGIN_CLIENT Permissions in the default settings (CUSTOM_DOMAIN/ui/console/instance?id=organizations)
Note: [Zitadel Manager Guide](/guides/manage/console/managers)
Note: [Zitadel Administrator Guide](/guides/manage/console/administrators)
3. Deploy login to Vercel: You can do so by directly clicking the [“Deploy” button](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#login-deploy) in our [repository](https://github.com/zitadel/zitadel)
4. If you have used the deploy button in the steps before, you will automatically be asked for this step. Enter the environment variables in Vercel
- PAT
@@ -6,7 +6,7 @@ sidebar_label: Onboard B2B customer
In this guide we will explain how you can create and set up new organizations in ZITADEL to help you with your onboarding flows.
Creating a new organization is the best choice for multi-tenancy use cases that require separation of customers, teams, or groups of users.
We will also explain how to leverage [Managers](/guides/manage/console/managers) to delegate self-service team management and configuration of policies to users of each organization.
We will also explain how to leverage [Administrators](/guides/manage/console/administrators) to delegate self-service team management and configuration of policies to users of each organization.
When you want to build an onboarding process for your business customers you have to go through the following steps:
@@ -27,7 +27,7 @@ ZITADEL does have multiple possibilities to achieve that process.
Each ZITADEL instance does automatically bring a management console with it. The [console](/guides/manage/console/console-overview) can be used to manage all your resources through a UI.
You can access it by calling the following URL: `${CUSTOM-DOMAIN}/ui/`
Make sure that your admins have a [Administrator role](/guides/manage/console/managers) with permissions on an instance level such as "INSTANCE_OWNER"
Make sure that your admins have a [Administrator role](/guides/manage/console/administrators) with permissions on an instance level such as "INSTANCE_OWNER"
### Create a customer
@@ -61,19 +61,19 @@ import CreateUser from "../../../guides/manage/console/_create-user.mdx";
#### Add Administrator Role to User
Now you need to assign the right administrator role to your user. In this case we want to give "ORG_OWNER".
If you do want to know more about the roles check out the [ZITADEL Managers Guide with the Role List](/guides/manage/console/managers)
If you do want to know more about the roles, check out the [ZITADEL Administrators Guide with the Role List](/guides/manage/console/administrators)
Go to the detail page of the organization and select the "+" button in the top right corner, where you already see a list of existing managers.
<img alt="Managers" src="/docs/img/guides/console/managers.png" width="200px" />
Go to the detail page of the organization and select the "+" button in the top right corner, where you already see a list of existing administrators.
<img alt="Administrators" src="/docs/img/guides/console/administrators.png" width="200px" />
import AddManager from "../../../guides/manage/console/_add_manager.mdx";
import AddAdministrator from "../../manage/console/_add_administrator.mdx";
<AddManager components={props.components} name="AddManager" />
<AddAdministrator components={props.components} name="AddAdministrator" />
### Invite Team Members
The first user of your customer is now ready to authenticate and manage resources in ZITADEL.
First task will be inviting a team member.
The first task will be inviting a team member.
We are now switching to the view of your customer's administrator user.
@@ -83,11 +83,11 @@ To show how you can use the self-management possibilities it is shown from the c
</Callout>
The Administrator user received an initialization e-mail after the user was created.
With the link in the email the admin will be able to setup a password and optionally some multi-factors.
With the link in the email, the admin will be able to set up a password and optionally some multi-factors.
As the administrator only has permission for its own organization the ZITADEL Management Console UI does look slightly different.
As the administrator only has permission for its own organization, the ZITADEL Management Console UI does look slightly different.
To invite a team member the admin has to repeat the steps you did before.
To invite a team member, the admin has to repeat the steps you did before.
1. [Create User](#create-user)
2. [Add role "ORG_OWNER" to the user](#add-administrator-role-to-user)
@@ -95,13 +95,13 @@ To invite a team member the admin has to repeat the steps you did before.
Your next step is to configure SSO so your users can authenticate with an existing user into ZITADEL.
First go to the Login Behavior and Security Settings.
First, go to the Login Behavior and Security Settings.
Make sure that the "External IDP allowed" is enabled.
This setting does generally allow users to authenticate with an external provider.
1. Go to the Settings Page
2. Navigate to Identity Providers
You might see already a list of activated providers here. If so, this is because some default providers are configured on the ZITADEL instances.
You might already see a list of activated providers here. If so, this is because some default providers are configured on the ZITADEL instances.
3. Configure the identity provider you need.
Follow our detailed configuration description of the different providers we have: [Configure the needed identity provider](/guides/integrate/identity-providers/introduction)
@@ -111,7 +111,7 @@ Let's assume you have configured Entra ID as an identity provider, and you want
This does need some specific configuration on your provider.
1. Go to the detail page of your configured identity provider (In this example Entra ID)
2. Enable "Automatic creation" in the optional settings. Optionally if you want to update the user information in ZITADEL, when they have changed in the Entra ID additionally enable "Automatic update"
2. Enable "Automatic creation" in the optional settings. Optionally, if you want to update the user information in ZITADEL, when they have changed in the Entra ID additionally enable "Automatic update"
3. Enable the "Account creation allowed" if it is not already
4. If you also want to allow users to link to an existing account, if they already have an account in ZITADEL, enable "Account linking allowed"
@@ -123,18 +123,18 @@ If your provider does not send all the required fields that ZITADEL needs to cre
#### Login with your user
Last step is that your user can login to ZITADEL and use the SSO account.
The last step is that your user can log in to ZITADEL and use the SSO account.
import OrgLoginDescription from "./_org_login_description.mdx";
<OrgLoginDescription components={props.components} name="OrgLodinDescription" />
Your user is now ready to login with SSO.
Your user is now ready to log in with SSO.
<img src="/docs/img/guides/solution-scenarios/user-login-with-external-idp.png" alt="User Login with SSO"/>
## Automated onboarding for your customers
If you want to start automating the process of onboarding your customers the following sections give you some guidance.
If you want to start automating the process of onboarding your customers, the following sections give you some guidance.
### Built-in register organization form
@@ -143,7 +143,7 @@ A basic form that allows a customer to enter an organization name and a user acc
When a user registers through this form, an organization and a user are created.
The user will automatically get the role "ORG_OWNER" withing ZITADEL and is able to manage the whole organization.
You can read more about the managers, roles and their meanings [here](/guides/manage/console/managers)
You can read more about the administrators, roles and their meanings [here](/guides/manage/console/administrators)
<img src="/docs/img/guides/solution-scenarios/register-organization.png" alt="Register Organization Form"/>
@@ -151,18 +151,18 @@ You can read more about the managers, roles and their meanings [here](/guides/ma
If you do not want to allow users to register organizations with this form, you can disable it with the following request27: [Restrict the instance features](/reference/api/admin/zitadel.admin.v1.AdminService.SetRestrictions)
Disabling the form makes sense, if your administrators manage new customers themselves or if you build your own form.
Disabling the form makes sense if your administrators manage new customers themselves or if you build your own form.
### Build your own form with setup organization request
If the built-in register form doesn't fulfill your needs we recommend building your own form.
If the built-in register form doesn't fulfill your needs, we recommend building your own form.
The administration API of ZITADEL, allows you to setup a new organization with a first administrator user.
The administration API of ZITADEL allows you to set up a new organization with a first administrator user.
The setup organization requests, has the possibility to specify an organization with its name and a domain.
You can directly send a human user with all the needed information like the profile, email, password. etc.
This request allows you only to setup a user with password authentication at the moment.
By specifying the roles you can define, which permission the user should have within ZITADEL.
Per default the user will automatically get "ORG_OWNER".
You can directly send a human user with all the necessary information like the profile, email, password. etc.
This request allows you only to set up a user with password authentication at the moment.
By specifying the roles you can define which permission the user should have within ZITADEL.
By default, the user will automatically get "ORG_OWNER".
<img src="/docs/img/guides/solution-scenarios/register-team-graphic.png" alt="Setup Organization with Admin User Graphic"/>
@@ -17,7 +17,7 @@ Users or service accounts can be assigned roles. You can do this via the ZITADEL
Follow the links below to assign roles to your users.
- [Add application roles via the ZITADEL Management Console](/guides/manage/console/roles)
- [Add administrator roles via the ZITADEL Management Console](/guides/manage/console/managers)
- [Add administrator roles via the ZITADEL Management Console](/guides/manage/console/administrators)
- [Add application roles via the ZITADEL Management API](/reference/api/project)
- [Add administrator roles to users via the ZITADEL Management API](/reference/api/management)
@@ -34,7 +34,7 @@ How to generate a token:
- [Generate tokens for users](/guides/integrate/login/oidc/login-users)
- [Generate tokens for service accounts](/guides/integrate/service-accounts/authenticate-service-accounts)
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 management console before requesting the token.
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 management console before requesting the token.
### Determine the audience
@@ -404,7 +404,7 @@ In [APIs listed under user grants in the management API](/reference/api/manageme
#### **1. [Search user grants](/reference/api/management/zitadel.management.v1.ManagementService.ListUserGrants)​**
Returns a list of user roles that match the search queries. A user with manager permissions will call this API and will also have to reside in the same organization as the user.
Returns a list of user roles that match the search queries. A user with administrator permissions will call this API and will also have to reside in the same organization as the user.
**URL: https://`${CUSTOM_DOMAIN}`/management/v1/users/grants/_search**
@@ -11,7 +11,7 @@ This guide explains ZITADEL service users and their role in facilitating secure
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.
Service users in combination with [Administrator](/concepts/structure/administrators) permissions are used to access ZITADEL's APIs, for example, to manage user resources.
Unlike users, service accounts don't rely on traditional login methods (e.g., username/password) and require alternative authentication mechanisms.
## Benefits of using Service Users
@@ -3,7 +3,7 @@ title: Configure personal access token authentication for service users
sidebar_label: Personal access token authentication
---
A Personal Access Token (PAT) is a ready to use token which can be used as _Authorization_ header.
A Personal Access Token (PAT) is a ready-to-use token that can be used as an _Authorization_ header.
At the moment ZITADEL only allows PATs for machine accounts (service users).
It is an alternative to the [private key JWT](./private-key-jwt) and [client credentials](./client-credentials). Read more about the different [authentication methods for service users](./authenticate-service-accounts).
@@ -22,12 +22,12 @@ It is an alternative to the [private key JWT](./private-key-jwt) and [client cre
## Grant role for ZITADEL
To be able to access the ZITADEL APIs your service user needs permissions to 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))
4. Give the user the role you need — for example, we choose Org Owner (More about [ZITADEL Permissions](/guides/manage/console/administrators))
![](../../../../public/img/guides/console-service-user-org-owner.gif)
@@ -39,12 +39,12 @@ Follow our guides on [how to access ZITADEL API](../zitadel-apis/access-zitadel-
### 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.
In this case your API needs to authenticate with ZITADEL and then do 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.
Because the PAT is a ready-to-use token, you can add it as an Authorization Header and send it in your requests to the ZITADEL API.
In this example we read the organization of the service user.
```bash
@@ -448,7 +448,7 @@ If you want to impersonate users by Token Exchange, the security settings of the
#### Impersonation permissions
Next we need to configure which users are allowed to impersonate other users. ZITADEL provides 4 [management roles](/guides/manage/console/managers):
Next, we need to configure which users are allowed to impersonate other users. ZITADEL provides 4 [management roles](/guides/manage/console/administrators):
| Name | Role | Description |
| ---------------------- | ------------------------- | ----------------------------------------------------------------- |
@@ -463,8 +463,8 @@ Next we need to configure which users are allowed to impersonate other users. ZI
#### Authenticated impersonator tokens
At this point the _portal_ web-app must have completed a code-flow login for an user with the `ORG_END_USER_IMPERSONATOR` ZITADEL role. The impersonator does not have a profile. In this case we only need the `openid` scope.
However, as we cannot extend audience during token exchange, it is important that the project scopes are requested for the impersonator during login.
At this point the _portal_ web-app must have completed a code-flow login for a user with the `ORG_END_USER_IMPERSONATOR` ZITADEL role. The impersonator does not have a profile. In this case we only need the `openid` scope.
However, as we cannot extend the audience during token exchange, it is important that the project scopes are requested for the impersonator during login.
```
openid urn:zitadel:iam:org:project:id:259254020357488642:aud urn:zitadel:iam:org:project:id:259256588127174658:aud urn:zitadel:iam:org:project:id:zitadel:aud
@@ -687,7 +687,7 @@ curl -L -X POST 'http://localhost:9000/oauth/v2/token' \
-d 'scope=openid profile email offline_access' | jq
```
Response with refresh token:
Response with a refresh token:
```bash
{
@@ -723,7 +723,7 @@ The response now caries an opaque token again, because that is what is configure
}
```
If we inspect the ID token we can see that the actor claim is preserved, even after token refresh:
If we inspect the ID token, we can see that the actor claim is preserved, even after token refresh:
```json
{
@@ -857,7 +857,7 @@ Above we gave some of the most straightforward use cases. Of course, you can com
## Audit trail
In the user view of the management console we can see whenever a new access token is created for a user.
In the user view of the management console, we can see whenever a new access token is created for a user.
The existing `Access Token created` event is also used in the case of a token exchange.
When there was an `actor_token` present during token exchange, we also log a `User impersonated` event.
@@ -878,4 +878,4 @@ In the [instance event list](/concepts/eventstore/overview) the `User impersonat
## Finishing notes
The current implementation of the Token Exchange grant was our first iteration on the subject.
We love to hear feedback from our user! This is a [GitHub discussion](https://github.com/zitadel/zitadel/discussions/7624) opened specifically for this purpose.
We love to hear feedback from our users! This is a [GitHub discussion](https://github.com/zitadel/zitadel/discussions/7624) opened specifically for this purpose.
@@ -7,13 +7,13 @@ This guide explains what ZITADEL APIs are and how to access ZITADEL APIs using a
## 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.
These APIs are offered through different protocols, including gRPC and REST.
Additionally, ZITADEL provides [SDKs for popular languages](/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.
* **Management API:** Used by organization administrators 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).
@@ -62,24 +62,24 @@ Via APIs23: * [Create User (Machine)](/reference/api/management/zitadel.manageme
## 2. Grant an Administrator Role to the Service User
ZITADEL Managers are Users who have permission to manage ZITADEL itself.
There are some different levels for managers.
ZITADEL Administrators are users who have permission to manage ZITADEL itself.
There are different levels of administrators.
- **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.
- **IAM Administrators**: This is the highest level. Users with IAM Administrator roles are able to manage the whole instance.
- **Organization Administrators**: Administrators at the Organization Level are able to manage everything within the granted Organization.
- **Project Administrators**: At this level, the user is able to manage a project.
- **Project Grant Administrators**: A project grant administrator manages projects which are granted by another organization.
There are different roles on each level. You can find more about the different roles here: [ZITADEL Administrator Roles](/guides/manage/console/managers#roles)
There are different roles on each level. You can find more about the different roles here: [ZITADEL Administrator Roles](/guides/manage/console/administrators#roles)
To be able to access the ZITADEL APIs your service user needs permissions to 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))
4. Give the user the role you need — for example, we choose Org Owner (More about [ZITADEL Permissions](/guides/manage/console/administrators))
![](../../../../public/img/console_org_manager_add.gif)
![](../../../../public/img/console_org_owner_add.gif)
## 3. Authenticate service user and request token
@@ -89,17 +89,17 @@ The [service user authentication](../service-accounts/authenticate-service-accou
This guide covers a specific case of service user authentication when requesting access to the [ZITADEL APIs](/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](/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.
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-accounts/private-key-jwt#2-register-a-private-key-for-your-service-user) and [create a JWT and sign with private key](../service-accounts/private-key-jwt#3-create-a-jwt-and-sign-it-with-your-private-key).
Follow the steps in this guide to [generate a key file](../service-accounts/private-key-jwt#2-register-a-private-key-for-your-service-user) and [create a JWT and sign with private key](../service-accounts/private-key-jwt#3-create-a-jwt-and-sign-it-with-your-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.**
**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
@@ -170,7 +170,7 @@ When using `client_secret_basic` on the token or introspection endpoints, provid
Authorization: "Basic " + base64( formUrlEncode(client_id) + ":" + formUrlEncode(client_secret) )
```
For an example see the [client secret basic authentication method reference](/apis/openidoauth/authn-methods#client-secret-basic).
For example, see the [client secret basic authentication method reference](/apis/openidoauth/authn-methods#client-secret-basic).
We recommend using an OpenID / OAuth library that handles the encoding for you.
#### Post request
@@ -216,9 +216,9 @@ curl --request GET \
### Personal access token (PAT)
A Personal Access Token (PAT) is a ready-to-use token which can be used as _Authorization_ header.
A Personal Access Token (PAT) is a ready-to-use token that can be used as an _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.
Because the PAT is a ready-to-use token, you can add it as an Authorization Header and send it in your requests to the ZITADEL API.
In this example, we read the organization of the service user.
```bash
@@ -7,7 +7,7 @@ ZITADEL leverages the power of eventsourcing, meaning every action and change wi
To provide you with greater flexibility and access to these events, ZITADEL has introduced an Event API.
This API allows you to easily retrieve and utilize the events generated within the system, enabling you to integrate them into your own system and respond to specific events as they occur.
You need to assign a user the [administrator role](/guides/manage/console/managers) IAM_OWNER_VIEWER or IAM_OWNER to access the Event API.
You need to assign a user the [administrator role](/guides/manage/console/administrators) 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).
## Request Events
@@ -119,8 +119,8 @@ curl --request POST \
### OIDC session
The following example shows you how you could use the events search to get all events where a user has authenticated using OIDC.
Also we include the refresh tokens in this example to know when the user has received a new token.
Sessions without tokens events may by created during implicit flow with ID Token only, which do not create an access token.
Also, we include the refresh tokens in this example to know when the user has received a new token.
Sessions without tokens events may by created during implicit flow with ID Token only, which does not create an access token.
```bash
curl --request POST \
@@ -170,9 +170,9 @@ The following example shows you how you could use the events search to find out
You have to include all the event types that tell you that a login attempt has failed.
In this case these are the following events:
- Password verification failed
- OTP check failed (Authenticator Apps like Authy, Google Authenticator, etc)
- Universal Second Factor (U2F) check failed (FaceID, WindowsHello, FingerPrint, etc)
- Passkey check failed (FaceID, WindowsHello, FingerPrint, etc)
- OTP check failed (Authenticator Apps like Authy, Google Authenticator, etc.)
- Universal Second Factor (U2F) check failed (FaceID, WindowsHello, FingerPrint, etc.)
- Passkey check failed (FaceID, WindowsHello, FingerPrint, etc.)
```bash
curl --request POST \