chore: naming inconsistency application (#11431)

This commit is contained in:
Wim Van Laer
2026-02-04 07:20:07 +00:00
committed by GitHub
parent 04c58c5b3f
commit 61d4060df3
96 changed files with 22550 additions and 22674 deletions
+1 -1
View File
@@ -104,4 +104,4 @@ Will be established as soon as the goal described above is reached.
This chapter provides a table linking to the detailed test results.
<DocCardList />
<DocCardList/>
+1 -1
View File
@@ -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, clients, 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 IAM 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>
@@ -49,7 +49,7 @@ This section details the migrated resources, including any breaking changes and
### General Changes
#### Sunsetting OpenAPI/REST Support in Favor of Connect RPC
While our v1 API already offered gRPC, it also provided a parallel REST/OpenAPI interface for clients who preferred making traditional HTTP calls.
While our v1 API already offered gRPC, it also provided a parallel REST/OpenAPI interface for applications who preferred making traditional HTTP calls.
In our v2 API, we are consolidating our efforts to provide a more streamlined and efficient development experience.
The primary change is the removal of the OpenAPI/REST interface.
@@ -62,10 +62,10 @@ For teams already using gRPC, your transition will be minimal.
For teams who were using the v1 REST API, migrating to v2 will involve adopting one of the following methods:
- Native gRPC: For the highest performance and to leverage features like bi-directional streaming.
- Connect RPC: For making CRUD-like (Create, Read, Update, Delete) calls over HTTP. This is the recommended path for most clients migrating from our v1 REST API.
- Connect RPC: For making CRUD-like (Create, Read, Update, Delete) calls over HTTP. This is the recommended path for most applications migrating from our v1 REST API.
A significant advantage of this new architecture remains the automatic generation of client libraries.
Based on our .proto service definitions, you can generate type-safe clients for your specific programming language, whether you use native gRPC or Connect RPC.
Based on our .proto service definitions, you can generate type-safe applications for your specific programming language, whether you use native gRPC or Connect RPC.
This eliminates the need to write boilerplate code for handling HTTP requests and parsing responses, leading to a more streamlined and less error-prone development process.
#### Contextual Information in the Request Body
@@ -3,7 +3,7 @@ title: Claims in ZITADEL
sidebar_label: Claims
---
ZITADEL asserts claims on different places according to the corresponding specifications or project and clients settings.
ZITADEL asserts claims on different places according to the corresponding specifications or project and applications settings.
Please check below the matrix for an overview where which scope is asserted.
| Claims | Userinfo | Introspection | ID Token | Access Token |
@@ -63,7 +63,7 @@ Please check below the matrix for an overview where which scope is asserted.
| given_name | `Road` | First name of the subject |
| given_name | `Road` | First name of the subject |
| iat | `1311280970` | Time of the token was issued at (as unix time) |
| iss | `${CUSTOM_DOMAIN}` | Issuing domain of a token |
| iss | `${CUSTOM_DOMAIN}` | Issuing domain of a token |
| jti | `69234237813329048` | Unique id of the token |
| locale | `en` | Language from the subject |
| name | `Road Runner` | The subjects full name |
@@ -110,9 +110,9 @@ ZITADEL reserves some claims to assert certain data. Please check out the [reser
|:--------------------------------------------------|:---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| urn:zitadel:iam:action:\{actionname}:log | `{"urn:zitadel:iam:action:appendCustomClaims:log": ["test log", "another test log"]}` | This claim is set during Actions as a log, e.g. if two custom claims with the same keys are set. |
| urn:zitadel:iam:org:domain:primary:\{domainname} | `{"urn:zitadel:iam:org:domain:primary": "acme.ch"}` | This claim represents the primary domain of the organization the user belongs to. |
| urn:zitadel:iam:org:project:roles | `{"urn:zitadel:iam:org:project:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }` | When roles are asserted, ZITADEL does this by providing the `id` and `primaryDomain` below the role. This gives you the option to check in which organization a user has the role on the current project (where your client belongs to). |
| urn:zitadel:iam:org:project:roles | `{"urn:zitadel:iam:org:project:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }` | When roles are asserted, ZITADEL does this by providing the `id` and `primaryDomain` below the role. This gives you the option to check in which organization a user has the role on the current project (where your application belongs to). |
| urn:zitadel:iam:org:project:\{projectid}:roles | `{"urn:zitadel:iam:org:project:id3:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }` | When roles are asserted, ZITADEL does this by providing the `id` and `primaryDomain` below the role. This gives you the option to check in which organization a user has the role on a specific project. |
| urn:zitadel:iam:user:metadata | `{"urn:zitadel:iam:user:metadata": [ {"key": "VmFsdWU=" } ] }` | The metadata claim will include all metadata of a user. The values are base64 encoded. |
| urn:zitadel:iam:user:resourceowner:id | `{"urn:zitadel:iam:user:resourceowner:id": "orgid"}` | This claim represents the user's organization ID. |
| urn:zitadel:iam:user:resourceowner:name | `{"urn:zitadel:iam:user:resourceowner:name": "ACME"}` | This claim represents the user's organization's name. |
| urn:zitadel:iam:user:resourceowner:primary_domain | `{"urn:zitadel:iam:user:resourceowner:primary_domain": "acme.ch"}` | This claim represents the user's organization's primary domain. |
| urn:zitadel:iam:user:resourceowner:id | `{"urn:zitadel:iam:user:resourceowner:id": "orgid"}` | This claim represents the user's organization ID. |
| urn:zitadel:iam:user:resourceowner:name | `{"urn:zitadel:iam:user:resourceowner:name": "ACME"}` | This claim represents the user's organization's name. |
| urn:zitadel:iam:user:resourceowner:primary_domain | `{"urn:zitadel:iam:user:resourceowner:primary_domain": "acme.ch"}` | This claim represents the user's organization's primary domain. |
@@ -44,7 +44,7 @@ authenticate the user in exchange for an authorization_code (authorization code
### Required request parameters
| Parameter | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| client_id | The id of your client as shown in Console. |
| redirect_uri | Callback uri of the authorization request where the code or tokens will be sent to. Must match exactly one of the preregistered in Console. |
| response_type | Determines whether a `code`, `id_token token` or just `id_token` will be returned. Most use cases will need `code`. See flow guide for more info. |
@@ -94,7 +94,7 @@ no additional parameters required
### Additional parameters
| Parameter | Description |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id_token_hint | Valid `id_token` (of an existing session) used to identity the subject. **SHOULD** be provided when using prompt `none`. |
| login_hint | A valid logon name of a user. Will be used for username inputs or preselecting a user on `select_account`. Be sure to encode the hint correctly using url encoding (especially when using `+` or alike in the loginname) |
| max_age | Seconds since the last active successful authentication of the user |
@@ -124,7 +124,7 @@ As per [OpenID Connect Core 1.0, Section 3.1.2.1](https://openid.net/specs/openi
When your `response_type` was `code` and no error occurred, the following response will be returned:
| Property | Description |
| -------- | ----------------------------------------------------------------------------- |
|----------|-------------------------------------------------------------------------------|
| code | Opaque string which will be necessary to request tokens on the token endpoint |
| state | Unmodified `state` parameter from the request |
@@ -133,7 +133,7 @@ When your `response_type` was `code` and no error occurred, the following respon
When your `response_type` was either `id_token` or `id_token token` and no error occurred, the following response will be returned:
| Property | Description |
| ------------ | ------------------------------------------------------------------------------------- |
|--------------|---------------------------------------------------------------------------------------|
| access_token | Only returned if `response_type` included `token` |
| expires_in | Number of second until the expiration of the `access_token` |
| id_token | An `id_token` of the authorized user |
@@ -265,6 +265,7 @@ curl --request POST \
```
#### Successful JWT profile response
| Property | Description |
| ------------ | ------------------------------------------------------------------------------------- |
| access_token | An `access_token` as JWT or opaque token |
@@ -331,6 +332,7 @@ Send a `client_assertion` as JWT for us to validate the signature against the re
</Tabs>
#### Successful refresh token response
| Property | Description |
| ------------- | ------------------------------------------------------------------------------------- |
| access_token | An `access_token` as JWT or opaque token |
@@ -379,6 +381,7 @@ curl --request POST \
```
#### Successful client credentials response
| Property | Description |
| ------------ | ------------------------------------------------------------------------------------- |
| access_token | An `access_token` as JWT or opaque token |
@@ -440,6 +443,7 @@ Send a `client_assertion` as JWT for us to validate the signature against the re
</Tabs>
#### Successful token exchange response
<TokenExchangeResponse components={props.components} />
#### Token types
@@ -537,6 +541,7 @@ Additionally and depending on the granted scopes, information about the authoriz
Check the [Claims](./claims) page if a specific claims might be returned and for detailed description.
### Error response
If the authorization fails, an HTTP 401 with `invalid_client` will be returned.
## userinfo_endpoint
@@ -554,6 +559,7 @@ curl --request GET \
```
### Successful userinfo response
If the `access_token` is valid, the information about the user depending on the granted scopes is returned.
Check the [Claims](./claims) page if a specific claims might be returned and for detailed description.
+14 -14
View File
@@ -3,17 +3,17 @@ title: GRPC Status Codes in ZITADEL
sidebar_label: GRPC Status Codes
---
| GRPC Number | GRPC Code | HTTP Status Code | HTTP Status Text |Description |
| :---------| :------------------- | ------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 0 | OK | 200 |OK | Not an error; returned on success. |
| 2 | UNKNOWN | 500 |Internal | Unknown error, this is sent if the error could not be identified as one of the errors described below |
| 3 | INVALID_ARGUMENT | 400 |Bad Request | The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name). |
| 4 | DEADLINE_EXCEEDED | 504 |Gateway Timeout | The deadline expired before the operation could complete. |
| 5 | NOT_FOUND | 404 |Not found | Some requested entity (e.g. user or project) was not found. |
| 6 | ALREADY_EXISTS | 409 |Conflict | The entity that a client attempted to create (e.g. user or project) already exists. |
| 7 | PERMISSION_DENIED | 403 |Forbidden |The caller does not have permission to execute the specified operation. |
| 9 | FAILED_PRECONDITION | 400 |Bad Request | The operation was rejected because the system is not in a state required for the operation's execution. e.g a project that is already deactivated, should be deactivated |
| 12 | UNIMPLEMENTED | 501 |Not Implemented |The operation is not implemented or is not supported/enabled in this service. |
| 13 | INTERNAL | 500 |Internal |Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors. |
| 14 | UNAVAILABLE | 503 |Service Unavailable | The service is currently unavailable. |
| 16 | UNAUTHENTICATED | 401 |Unauthorized |The request does not have valid authentication credentials for the operation. |
| GRPC Number | GRPC Code | HTTP Status Code | HTTP Status Text | Description |
|:------------|:--------------------|------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 0 | OK | 200 | OK | Not an error; returned on success. |
| 2 | UNKNOWN | 500 | Internal | Unknown error, this is sent if the error could not be identified as one of the errors described below |
| 3 | INVALID_ARGUMENT | 400 | Bad Request | The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name). |
| 4 | DEADLINE_EXCEEDED | 504 | Gateway Timeout | The deadline expired before the operation could complete. |
| 5 | NOT_FOUND | 404 | Not found | Some requested entity (e.g. user or project) was not found. |
| 6 | ALREADY_EXISTS | 409 | Conflict | The entity that a client attempted to create (e.g. user or project) already exists. |
| 7 | PERMISSION_DENIED | 403 | Forbidden | The caller does not have permission to execute the specified operation. |
| 9 | FAILED_PRECONDITION | 400 | Bad Request | The operation was rejected because the system is not in a state required for the operation's execution. e.g a project that is already deactivated, should be deactivated |
| 12 | UNIMPLEMENTED | 501 | Not Implemented | The operation is not implemented or is not supported/enabled in this service. |
| 13 | INTERNAL | 500 | Internal | Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors. |
| 14 | UNAVAILABLE | 503 | Service Unavailable | The service is currently unavailable. |
| 16 | UNAUTHENTICATED | 401 | Unauthorized | The request does not have valid authentication credentials for the operation. |