# Which Problems Are Solved
There were no guideline to how design future APIs and their endpoints.
The V3 documentation was to specific and targeted towards internal
stakeholders.
This PR is intended as base and kept to the minimum. If more details or
additional guideline or rules are needed, they will be added in the
future.
# How the Problems Are Solved
- Removed the V3 description and corresponding examples.
- Provided general guideline for the design of APIs, which includes the
structure, naming, versioning, error handling and more.
# Additional Changes
None
# Additional Context
closes#9184
---------
Co-authored-by: Maximilian <mpa@zitadel.com>
Co-authored-by: Silvan <27845747+adlerhurst@users.noreply.github.com>
# Which Problems Are Solved
The community implemented an example for integrating fastAPI with
Zitadel.
So far this example has not been listed.
# How the Problems Are Solved
The example is now listed
Disclaimer is added, that some of the examples are not maintained by us
# Which Problems Are Solved
The rate limit policy doesn't match the actually applied rate limits.
# How the Problems Are Solved
The rate limit policy is updated.
# Additional Conext
- https://github.com/caos/infra/pull/1141
---------
Co-authored-by: Florian Forster <florian@zitadel.com>
# Which Problems Are Solved
No benchmarks for v2.70.0 were provided so far.
# How the Problems Are Solved
Benchmarks added
# Additional changes
- it's now possible to plot multiple charts, one chart per `metric_name`
# Which Problems Are Solved
Some OAuth2 and OIDC providers require the use of PKCE for all their
clients. While ZITADEL already recommended the same for its clients, it
did not yet support the option on the IdP configuration.
# How the Problems Are Solved
- A new boolean `use_pkce` is added to the add/update generic OAuth/OIDC
endpoints.
- A new checkbox is added to the generic OAuth and OIDC provider
templates.
- The `rp.WithPKCE` option is added to the provider if the use of PKCE
has been set.
- The `rp.WithCodeChallenge` and `rp.WithCodeVerifier` options are added
to the OIDC/Auth BeginAuth and CodeExchange function.
- Store verifier or any other persistent argument in the intent or auth
request.
- Create corresponding session object before creating the intent, to be
able to store the information.
- (refactored session structs to use a constructor for unified creation
and better overview of actual usage)
Here's a screenshot showing the URI including the PKCE params:

# Additional Changes
None.
# Additional Context
- Closes#6449
- This PR replaces the existing PR (#8228) of @doncicuto. The base he
did was cherry picked. Thank you very much for that!
---------
Co-authored-by: Miguel Cabrerizo <doncicuto@gmail.com>
Co-authored-by: Stefan Benz <46600784+stebenz@users.noreply.github.com>
# Which Problems Are Solved
The OAuth2 Device Authorization Grant could not yet been handled through
the new login UI, resp. using the session API.
This PR adds the ability for the login UI to get the required
information to display the user and handle their decision (approve with
authorization or deny) using the OIDC Service API.
# How the Problems Are Solved
- Added a `GetDeviceAuthorizationRequest` endpoint, which allows getting
the `id`, `client_id`, `scope`, `app_name` and `project_name` of the
device authorization request
- Added a `AuthorizeOrDenyDeviceAuthorization` endpoint, which allows to
approve/authorize with the session information or deny the request. The
identification of the request is done by the `device_authorization_id` /
`id` returned in the previous request.
- To prevent leaking the `device_code` to the UI, but still having an
easy reference, it's encrypted and returned as `id`, resp. decrypted
when used.
- Fixed returned error types for device token responses on token
endpoint:
- Explicitly return `access_denied` (without internal error) when user
denied the request
- Default to `invalid_grant` instead of `access_denied`
- Explicitly check on initial state when approving the reqeust
- Properly handle done case (also relates to initial check)
- Documented the flow and handling in custom UIs (according to OIDC /
SAML)
# Additional Changes
- fixed some typos and punctuation in the corresponding OIDC / SAML
guides.
- added some missing translations for auth and saml request
# Additional Context
- closes#6239
---------
Co-authored-by: Tim Möhlmann <tim+github@zitadel.com>
# Which Problems Are Solved
Due to other priorities we decided to push the implementation of user
schema back in the roadmap.
As the feature is not yet complete and can't be tested/used, the API
Docs V3 for user schema and user lead to confusion.
# How the Problems Are Solved
I removed the api docs for user schema and user v3 from the sidenav for
the moment
Co-authored-by: Livio Spring <livio.a@gmail.com>
# Which Problems Are Solved
OIDC applications can configure the used login version, which is
currently not possible for SAML applications.
# How the Problems Are Solved
Add the same functionality dependent on the feature-flag for SAML
applications.
# Additional Changes
None
# Additional Context
Closes#9267
Follow up issue for frontend changes #9354
---------
Co-authored-by: Livio Spring <livio.a@gmail.com>
# Which Problems Are Solved
Currently it is not always obvious if a feature is in beta state, also I
don't know where I can add my feedback if I test the feature.
# How the Problems Are Solved
- Mark beta features with [beta] in sidenav
- Add note on feature description where to add feedback
# Which Problems Are Solved
- Lack of documentation for the SCIM v2 interface
# How the Problems Are Solved
- Introduced a new documentation page detailing the SCIM v2 interface
# Additional Context
Part of #8140
---------
Co-authored-by: Fabienne Bühler <fabienne@zitadel.com>
# Which Problems Are Solved
SAML session implemented, but no how-to comparable to the OIDC sessions
for custom login available.
# How the Problems Are Solved
Added documentation, which should be also comparable with the OIDC
session for ease-of-use.
# Additional Changes
Added generated SAML API docs.
# Additional Context
Closes#9088
Follow-up issue #9267
---------
Co-authored-by: Fabienne Bühler <fabienne@zitadel.com>
Co-authored-by: Livio Spring <livio.a@gmail.com>
# Which Problems Are Solved
Small update to docs/docs/concepts/features/selfservice.md to fix issue
in grammar
Co-authored-by: Iraq Jaber <IraqJaber@gmail.com>
# Which Problems Are Solved
As we are going into the Beta testing phase of our new typescript login
(login V2), we need to have a documentation about the capabilities, how
to test, and what the current limitations are.
# How the Problems Are Solved
Added new section for the Login V2
---------
Co-authored-by: Max Peintner <max@caos.ch>
Co-authored-by: Max Peintner <peintnerm@gmail.com>
# Which Problems Are Solved
In versions previous to v2.66 it was possible to set a different
resource owner on project grants. This was introduced with the new
resource based API. The resource owner was possible to overwrite using
the x-zitadel-org header.
Because of this issue project grants got the wrong resource owner,
instead of the owner of the project it got the granted org which is
wrong because a resource owner of an aggregate is not allowed to change.
# How the Problems Are Solved
- The wrong owners of the events are set to the original owner of the
project.
- A new event is pushed to these aggregates `project.owner.corrected`
- The projection updates the owners of the user grants if that event was
written
# Additional Changes
The eventstore push function (replaced in version 2.66) writes the
correct resource owner.
# Additional Context
closes https://github.com/zitadel/zitadel/issues/9072
# Which Problems Are Solved
Wrongly not returned but documented 'nbf' claim in ID token.
# How the Problems Are Solved
Correct documentation to not include 'nbf' in ID token.
# Additional Changes
None
# Additional Context
None
# Which Problems Are Solved
Commands for installing compose stacks with reverse proxies don't work.
# How the Problems Are Solved
- The `docker compose up` commands are fixed by specifying all necessary
services to spin up. This is obviously not (or not with all docker
compose versions) resolved by the dependencies declarations.
- The initial postgres admin username is postgres.
- Fix postgres health check to succeed before the init job created the
DB.
- A hint tells the user to install the grpcurl binary.
# Additional Changes
- Passing `--wait` to `docker compose up` doesn't require us to sleep
for exactly three seconds.
- It looks to me like the order of the depends_on declaration for
zitadel matters, but I don't understand why. I changed it so that it's
for sure correct.
- Silenced some command outputs
- Removed the version property from all compose files to avoid the
following warning
```
WARN[0000] /tmp/caddy-example/docker-compose-base.yaml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
```
# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/9115
This is the easiest way to test the updated docs:
```bash
# Use this PR branches files:
export ZITADEL_CONFIG_FILES=https://raw.githubusercontent.com/zitadel/zitadel/refs/heads/fix-reverse-proxy-guides/docs/docs/self-hosting/manage/reverseproxy
```
The rest of the commands as described in
https://docs-git-fix-reverse-proxy-guides-zitadel.vercel.app/docs/self-hosting/manage/reverseproxy/caddy

# Which Problems Are Solved
It is currently not possible to use SAML with the Session API.
# How the Problems Are Solved
Add SAML service, to get and resolve SAML requests.
Add SAML session and SAML request aggregate, which can be linked to the
Session to get back a SAMLResponse from the API directly.
# Additional Changes
Update of dependency zitadel/saml to provide all functionality for
handling of SAML requests and responses.
# Additional Context
Closes#6053
---------
Co-authored-by: Livio Spring <livio.a@gmail.com>
# Which Problems Are Solved
- Fixed a typo in docs/docs/apis/observability/health.md where
`Enpoints` should be `Endpoints`
<!--
# How the Problems Are Solved
# Additional Changes
# Additional Context
-->
Co-authored-by: Fabi <fabienne@zitadel.com>
Co-authored-by: Livio Spring <livio.a@gmail.com>
# Which Problems Are Solved
Integration guide with event API examples used outdated
`user.token.added` events which are no longer produced by ZITADEL.
# How the Problems Are Solved
Modify the example to use events from the `oidc_session` aggregate.
# Additional Changes
- Add a TODO for related SAML events.
# Additional Context
- Related to https://github.com/zitadel/zitadel/issues/8983
# Which Problems Are Solved
The current "stable" release tag was no longer maintained.
# How the Problems Are Solved
Remove the tag from the docs.
# Additional Changes
Update the docs to reflect that test run with Ubuntu 22.04 instead of
20.04.
# Additional Context
- relates to https://github.com/zitadel/zitadel/issues/8884
# Which Problems Are Solved
Some videos in the guides start playing automatically. This prevents a
great user / developer experience.
# How the Problems Are Solved
Stop autoplay.
# Additional Changes
None
# Additional Context
Discussed internally
Hello everyone,
To support Korean-speaking users who may experience challenges in using
this excellent tool due to language barriers, I have added Korean
language support with the help of ChatGPT.
I hope that this contribution allows ZITADEL to be more useful and
accessible to Korean-speaking users.
Thank you.
---
안녕하세요 여러분, 언어의 어려움으로 이 훌륭한 도구를 활용하는데 곤란함을 겪는 한국어 사용자들을 위하여 ChatGPT의 도움을
받아 한국어 지원을 추가하였습니다.
이 기여를 통해 ZITADEL이 한국어 사용자들에게 유용하게 활용되었으면 좋겠습니다.
감사합니다.
Co-authored-by: Max Peintner <max@caos.ch>
# Which Problems Are Solved
The action v2 messages were didn't contain anything providing security
for the sent content.
# How the Problems Are Solved
Each Target now has a SigningKey, which can also be newly generated
through the API and returned at creation and through the Get-Endpoints.
There is now a HTTP header "Zitadel-Signature", which is generated with
the SigningKey and Payload, and also contains a timestamp to check with
a tolerance if the message took to long to sent.
# Additional Changes
The functionality to create and check the signature is provided in the
pkg/actions package, and can be reused in the SDK.
# Additional Context
Closes#7924
---------
Co-authored-by: Livio Spring <livio.a@gmail.com>
Bumps [cross-spawn](https://github.com/moxystudio/node-cross-spawn) from
7.0.3 to 7.0.6.
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/moxystudio/node-cross-spawn/blob/master/CHANGELOG.md">cross-spawn's
changelog</a>.</em></p>
<blockquote>
<h3><a
href="https://github.com/moxystudio/node-cross-spawn/compare/v7.0.5...v7.0.6">7.0.6</a>
(2024-11-18)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>update cross-spawn version to 7.0.5 in package-lock.json (<a
href="f700743918">f700743</a>)</li>
</ul>
<h3><a
href="https://github.com/moxystudio/node-cross-spawn/compare/v7.0.4...v7.0.5">7.0.5</a>
(2024-11-07)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>fix escaping bug introduced by backtracking (<a
href="640d391fde">640d391</a>)</li>
</ul>
<h3><a
href="https://github.com/moxystudio/node-cross-spawn/compare/v7.0.3...v7.0.4">7.0.4</a>
(2024-11-07)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>disable regexp backtracking (<a
href="https://redirect.github.com/moxystudio/node-cross-spawn/issues/160">#160</a>)
(<a
href="5ff3a07d9a">5ff3a07</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="77cd97f3ca"><code>77cd97f</code></a>
chore(release): 7.0.6</li>
<li><a
href="6717de49ff"><code>6717de4</code></a>
chore: upgrade standard-version</li>
<li><a
href="f700743918"><code>f700743</code></a>
fix: update cross-spawn version to 7.0.5 in package-lock.json</li>
<li><a
href="9a7e3b2165"><code>9a7e3b2</code></a>
chore: fix build status badge</li>
<li><a
href="085268352d"><code>0852683</code></a>
chore(release): 7.0.5</li>
<li><a
href="640d391fde"><code>640d391</code></a>
fix: fix escaping bug introduced by backtracking</li>
<li><a
href="bff0c87c8b"><code>bff0c87</code></a>
chore: remove codecov</li>
<li><a
href="a7c6abc6fe"><code>a7c6abc</code></a>
chore: replace travis with github workflows</li>
<li><a
href="9b9246e096"><code>9b9246e</code></a>
chore(release): 7.0.4</li>
<li><a
href="5ff3a07d9a"><code>5ff3a07</code></a>
fix: disable regexp backtracking (<a
href="https://redirect.github.com/moxystudio/node-cross-spawn/issues/160">#160</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/moxystudio/node-cross-spawn/compare/v7.0.3...v7.0.6">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
You can disable automated security fix PRs for this repo from the
[Security Alerts
page](https://github.com/zitadel/zitadel/network/alerts).
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Max Peintner <max@caos.ch>
# Which Problems Are Solved
Some links are pointing to the deprecated API v1
# How the Problems Are Solved
Change the link to the API V2
# Additional Changes
For the moment, I don't have the time to add more links in the API v1
pages.
Maybe later, when I will have time, I will add more links
---------
Co-authored-by: Fabi <fabienne@zitadel.com>
# Which Problems Are Solved
Organizations are ofter searched for by ID or primary domain. This
results in many redundant queries, resulting in a performance impact.
# How the Problems Are Solved
Cache Organizaion objects by ID and primary domain.
# Additional Changes
- Adjust integration test config to use all types of cache.
- Adjust integration test lifetimes so the pruner has something to do
while the tests run.
# Additional Context
- Closes#8865
- After #8902
# Which Problems Are Solved
Explain the usage of the new cache mechanisms.
# How the Problems Are Solved
Provide a dedicated page on caches with reference to `defaults.yaml`.
# Additional Changes
- Fix a broken link tag in token exchange docs.
# Additional Context
- Closes#8855
ZITADEL CI/CD / core-unit-test (push) Has been skipped
ZITADEL CI/CD / core-integration-test (push) Has been skipped
ZITADEL CI/CD / console (push) Failing after 9m42s
ZITADEL CI/CD / lint (push) Has been skipped
ZITADEL CI/CD / version (push) Successful in 11m8s
ZITADEL CI/CD / compile (push) Has been skipped
ZITADEL CI/CD / container (push) Has been skipped
ZITADEL CI/CD / e2e (push) Has been skipped
ZITADEL CI/CD / release (push) Has been skipped
# Which Problems Are Solved
As we switched to PostgreSQL with our cloud zitadel, we now want to
recommend it instead of CockroachDB.
# How the Problems Are Solved
Replaced the recommend section with postgresql
ZITADEL CI/CD / compile (push) Blocked by required conditions
ZITADEL CI/CD / core-unit-test (push) Blocked by required conditions
ZITADEL CI/CD / core-integration-test (push) Blocked by required conditions
ZITADEL CI/CD / lint (push) Blocked by required conditions
ZITADEL CI/CD / container (push) Blocked by required conditions
ZITADEL CI/CD / e2e (push) Blocked by required conditions
ZITADEL CI/CD / release (push) Blocked by required conditions
Code Scanning / CodeQL-Build (go) (push) Waiting to run
Code Scanning / CodeQL-Build (javascript) (push) Waiting to run
# Which Problems Are Solved
1. Postgres spams FATAL: role "root" does not exist as mentioned in
https://github.com/zitadel/zitadel/discussions/7832 (even with -U)
2. The compose commands for a ZITADEL deployment with initial service
account key don't work out-of-the box with a non-root user, because
docker creates non-existing directories to bind-mount with root
ownership.

```
time="2024-10-29T09:37:13Z" level=error msg="migration failed" caller="/home/runner/work/zitadel/zitadel/internal/migration/migration.go:68" error="open /machinekey/zitadel-admin-sa.json: permission denied" name=03_default_instance
time="2024-10-29T09:37:13Z" level=fatal msg="migration failed" caller="/home/runner/work/zitadel/zitadel/cmd/setup/setup.go:248" error="open /machinekey/zitadel-admin-sa.json: permission denied" name=03_default_instance
```
# How the Problems Are Solved
1. The branch bases on https://github.com/zitadel/zitadel/pull/8826. The
env vars are cleaned up and prettified across compose files.
2. A command is added to the docs that creates the directory with the
current users permission. The ZITADEL container runs with the current
users ID.
# Additional Context
- Replaces https://github.com/zitadel/zitadel/pull/8826
- Discussion https://github.com/zitadel/zitadel/discussions/7832
- Closes https://github.com/zitadel/zitadel/issues/7725
---------
Co-authored-by: m4tu4g <71326926+m4tu4g@users.noreply.github.com>
Code Scanning / CodeQL-Build (javascript) (push) Waiting to run
ZITADEL CI/CD / core (push) Waiting to run
ZITADEL CI/CD / console (push) Waiting to run
ZITADEL CI/CD / version (push) Waiting to run
ZITADEL CI/CD / compile (push) Blocked by required conditions
ZITADEL CI/CD / core-unit-test (push) Blocked by required conditions
ZITADEL CI/CD / core-integration-test (push) Blocked by required conditions
ZITADEL CI/CD / lint (push) Blocked by required conditions
ZITADEL CI/CD / container (push) Blocked by required conditions
ZITADEL CI/CD / e2e (push) Blocked by required conditions
ZITADEL CI/CD / release (push) Blocked by required conditions
Code Scanning / CodeQL-Build (go) (push) Waiting to run
- **docs: s/Secondfactor/Second factor/**
- **docs: s/IDP/IdP/**
- **docs: s/Hardwaretokens/Hardware tokens/**
- **docs: standardize multi-factor vs multi factor vs multifactor**
# Which Problems Are Solved
- English strings are improved
# How the Problems Are Solved
- With better strings
---------
Co-authored-by: Fabi <fabienne@zitadel.com>
# Which Problems Are Solved
- The addorgmember request shows a wrong example in the api
documentation
- Broken Links on actions feature description
# How the Problems Are Solved
- Change example of AddOrgMember API Docs
- Point towards correct links
---------
Co-authored-by: Tim Möhlmann <tim+github@zitadel.com>
- Fully translated all UI elements, documentation, and error messages
- Added Hungarian as a new supported language option
- Updated language selection menus and related configuration files
- Ensured consistency across all translated content
# Which Problems Are Solved
- ZITADEL was not accessible for Hungarian-speaking users due to lack of
language support
- Hungarian users had to rely on English or other languages to use the
platform
- Potential user base was limited due to language barrier
# How the Problems Are Solved
- Translated all user interface elements, including console and login
interfaces
- Translated all documentation files to Hungarian
- Added Hungarian translations for all error messages and notifications
- Implemented Hungarian as a selectable language option in the system
# Additional Changes
- Updated language selection menus to include Hungarian
- Modified configuration files to support Hungarian language
- Ensured consistent terminology and style across all translated content
- Added Hungarian language option to relevant dropdown menus and
settings
# Additional Context
- Relates to the ongoing internationalization efforts of ZITADEL
- Enhances accessibility for Hungarian-speaking developers and users
- Expands ZITADEL's potential user base in Hungary and
Hungarian-speaking regions
---------
Co-authored-by: Max Peintner <max@caos.ch>
Co-authored-by: Tim Möhlmann <tim+github@zitadel.com>
Co-authored-by: Stefan Benz <46600784+stebenz@users.noreply.github.com>
# Which Problems Are Solved
The `/oauth/v1` path prefix is duplicated, which is an error in most
proxies.
# How the Problems Are Solved
Remove the duplicate path prefix from the docs.
Co-authored-by: Fabi <fabienne@zitadel.com>
# Which Problems Are Solved
The current docs of the Authorization code grant do not mention that for
the authentication method type "None (PKCE)", you need to additionally
provide a `client_id` parameter.
# How the Problems Are Solved
Missing parameter is added to the docs.
# Additional Context
- Closes#8506