# Which Problems Are Solved
The API error reference page (`/docs/apis/errors`) shows "Couldn't load
the error reference. Try reloading the page." instead of the table. This
started after #12502 switched the page from a static import of
`data.json` to fetching it from a route handler at runtime.
# How the Problems Are Solved
`apps/docs` is served under `basePath: '/docs'` (`next.config.mjs`). The
fetch call in `ErrorReference` used `/api/error-reference`, but a plain
`fetch()` does not get the basePath prefix added the way `<Link>` and
`router.push()` do, so the request always 404'd. Fetches
`/docs/api/error-reference` instead, the actual prefixed route.
# Additional Changes
None.
# Additional Context
- Follow-up for #12502
- Confirmed locally: `curl localhost:3000/api/error-reference` returns
404, `curl localhost:3000/docs/api/error-reference` returns 200 with the
full catalog
Co-authored-by: Rajat Singh <[email protected]>
## Summary
- Add a searchable catalog of every error ID ZITADEL's gRPC/Connect APIs
can return (`content/apis/errors.mdx`), wired into the sidebar next to
"gRPC Status Codes" (with a cross-link added there too). There was
previously no such reference — error IDs are assigned ad hoc at ~3,800
call sites across the backend.
- `scripts/generate-error-reference.ts` scans `internal/**/*.go` and
`backend/**/*.go` for `zerrors.Throw*()` call sites, resolves i18n
messages, and clusters ~3,200 distinct IDs into ~1,160 distinct causes
by (subsystem, gRPC code, message) — so identical causes are merged into
one entry instead of repeated ~3,200 times.
- Detects real ID collisions (same ID thrown for genuinely different
reasons at different call sites) and surfaces them as warnings, rather
than silently merging them.
- Generates a worked example API response for every cause.
- 116 of the highest-impact causes (covering the majority of call sites)
carry an explanation written against the actual source rather than the
raw message text; the rest carry a mechanically derived explanation —
both are visibly labeled by source so the depth of research is
transparent.
- New `ErrorReference` component renders the catalog as a searchable,
collapsible subsystem → gRPC code → cause tree.
The generator is a standalone script (`pnpm generate:error-reference` in
`apps/docs`), not wired into the docs build's `generate` chain, since
scanning the whole Go backend on every docs build would be wasteful. The
generated `data.json` and the curated overrides are committed, the same
way `content/apis/benchmarks/**/output.json` is already committed
despite being externally generated.
## Test plan
- [x] `pnpm nx run @zitadel/docs:check-types` passes
- [x] `pnpm nx run @zitadel/docs:lint` passes
- [x] `pnpm nx run @zitadel/docs:check-links` passes
- [x] Verified locally in `pnpm nx run @zitadel/docs:dev`: page renders,
tree expands/collapses, search filters by ID/message, collision warnings
render correctly (e.g. `AUTHZ-Kl3p0`)
---------
Co-authored-by: Rajat Singh <[email protected]>
Co-authored-by: Claude Sonnet 5 <[email protected]>
Co-authored-by: Marco A. <[email protected]>
Link the YouTube walkthrough at the end of the quickstart page for users
who prefer watching over reading.
Co-authored-by: Rajat Singh <[email protected]>
The changelog page on zitadel.com was removed for being unmaintained,
leaving the docs sidebar link 404ing.
Co-authored-by: Rajat Singh <[email protected]>
## Summary
- Add a new guide documenting how to let users delete their own account
via the User v2 API's `DeleteUser` endpoint, gated by the
`user.self.delete` permission (granted via `ORG_USER_SELF_MANAGER`)
- Link the new guide from the self-service concepts page and sidebar
- Add the `ORG_USER_SELF_MANAGER` role to the administrators reference
table
## Test plan
- [x] Verified the new and updated pages render correctly in local dev
(`pnpm dev`)
replaces #12455 and #12457 (branch got renamed from
`docs/human-pat-clarification`, which auto-closed #12457).
Co-authored-by: Rajat Singh <[email protected]>
## Which Problems Are Solved
There is currently a knowledge gap in the documentation where users are
unclear on if or why human accounts cannot have Personal Access Tokens
(PATs), which has led to confusion in community channels like Discord
and GitHub.
## How the Problems Are Solved
Clarified that human PATs are currently not supported in the Personal
Access Token documentation and added a direct link to GitHub Issue
#10915 so users can track and upvote this capability.
## Additional Changes
None
## Additional Context
None
---------
Signed-off-by: Rajat Singh <[email protected]>
Co-authored-by: Rajat Singh <[email protected]>
## Which Problems Are Solved
The callout added in #12335 included a link to a GitHub discussion which
will become outdated and difficult to maintain.
## How the Problems Are Solved
Removes the discussion link from the ZITADEL Cloud bullet point in the
TOTP issuer callout, keeping the rest of the callout intact.
Co-authored-by: Rajat Singh <[email protected]>
# Which Problems Are Solved
- No documentation explained that the TOTP issuer name defaults to
"ZITADEL" and is not derived from the domain
- No documentation clarified how to change it on self-hosted (env var
only, Helm values don't work)
- No documentation communicated that it is not configurable on ZITADEL
Cloud
# How the Problems Are Solved
- Adds a callout in the MFA section of the default settings page
covering both self-hosted
(ZITADEL_SYSTEMDEFAULTS_MULTIFACTORS_OTP_ISSUER) and cloud (not
configurable, discussion link)
# Additional Changes
None
# Additional Context
- https://github.com/zitadel/zitadel/discussions/5453
Signed-off-by: Rajat Singh <[email protected]>
Co-authored-by: Rajat Singh <[email protected]>
# Which Problems Are Solved
- The documentation had no guidance for debugging auto-user-creation
failures caused by unexpected or missing claims from an external IdP,
leaving users without a path forward when they see a
`SetHumanProfile.GivenName` validation error during OIDC login.
# How the Problems Are Solved
- Adds a troubleshooting section to the Actions V2 response manipulation
guide explaining how to use the `RetrieveIdentityProviderIntent` webhook
to inspect `rawInformation` and identify claim key mismatches from the
external IdP.
# Additional Changes
- None
Signed-off-by: Rajat Singh <[email protected]>
Co-authored-by: Rajat Singh <[email protected]>
<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->
# Which Problems Are Solved
Replace this example text with a concise list of problems that this PR
solves.
For example:
- Generic OIDC Identity Provider - help button opens Google
Configuration page
# How the Problems Are Solved
Replace this example text with a concise list of changes that this PR
introduces.
For example:
- made the URL update in `provider-oidc.component.html`
# Additional Context
Replace this example with links to related issues, discussions, discord
threads, or other sources with more context.
Use the Closing #issue syntax for issues that are resolved with this PR.
- Closes#11505
---------
Co-authored-by: Rajat Singh <[email protected]>
Co-authored-by: Copilot <[email protected]>
<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->
# Which Problems Are Solved
- Added a new "Knowledge Base" card to the Get Started section.
# How the Problems Are Solved
- Updating the index.mdx file with [Knowledge Base
Link](https://help.zitadel.com/)
Co-authored-by: Rajat Singh <[email protected]>
# Which Problems Are Solved
- The Node.js client library link in the SDK examples was outdated and
led to a broken or incorrect destination.
# How the Problems Are Solved
- Updated the Node.js client library link in the SDK examples to point
to the correct `/zitadel-node` repository.
# Additional Changes
- None.
# Additional Context
- N/A
Co-authored-by: Rajat Singh <[email protected]>
# Which Problems Are Solved
Duplicate of https://github.com/zitadel/zitadel/pull/11405
- Users migrating from Actions V1 to V2 lack comprehensive documentation
explaining the architectural differences and migration patterns
- The existing migration guide doesn't provide enough context on why
Actions changed and how to map V1 concepts to V2
- No clear reference table mapping common use cases to the appropriate
V2 execution types
# How the Problems Are Solved
- Added a new comprehensive migration guide
(`actions-v1-to-v2-migration.md`) covering:
- Deprecation notice for Actions V1 (sunsetting in ZITADEL V5)
- Architecture deep dive comparing V1 (embedded JavaScript) vs V2
(webhook model)
- Key architectural differences table
- Business benefits of migrating to V2
- Use case mapping table with links to ready-to-deploy Cloudflare Worker
examples
- Detailed flow explanations for Internal Authentication, External
Authentication, Complement Token, and SAML Response customization
---------
Co-authored-by: Rajat Singh <[email protected]>
<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->
# Which Problems Are Solved
Added guide to setup webhook.site
# How the Problems Are Solved
Users can now learn how to setup listener over the internet
# Additional Changes
none
# Additional Context
none
---------
Signed-off-by: Rajat Singh <[email protected]>
Co-authored-by: Rajat Singh <[email protected]>
Added a step-by-step guide for Keycloak to Zitadel migration for the
workshop tomorrow
---------
Signed-off-by: RAJAT SINGH <[email protected]>
Signed-off-by: Rajat Singh <[email protected]>
Co-authored-by: RAJAT SINGH <[email protected]>
Co-authored-by: Rajat Singh <[email protected]>
<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->
# Which Problems Are Solved
Removed the scopes/claims that were not used.
# How the Problems Are Solved
Made small changes in readme that fixes it.
Signed-off-by: RAJAT SINGH <[email protected]>
Co-authored-by: RAJAT SINGH <[email protected]>
