From 94ac4237a9211d4801e0b9423c4ce4b289f06585 Mon Sep 17 00:00:00 2001 From: Rajat Singh <17253992+rajatcing@users.noreply.github.com> Date: Thu, 16 Jul 2026 18:35:44 +0200 Subject: [PATCH] docs: add user self-deletion guide (#12458) ## 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 --- .../content/concepts/features/selfservice.mdx | 4 ++ .../guides/manage/console/administrators.mdx | 2 + .../guides/manage/user/self-deletion.mdx | 48 +++++++++++++++++++ apps/docs/lib/sidebar-data.ts | 1 + 4 files changed, 55 insertions(+) create mode 100644 apps/docs/content/guides/manage/user/self-deletion.mdx diff --git a/apps/docs/content/concepts/features/selfservice.mdx b/apps/docs/content/concepts/features/selfservice.mdx index 48a2695d0..a6b8ca1fd 100644 --- a/apps/docs/content/concepts/features/selfservice.mdx +++ b/apps/docs/content/concepts/features/selfservice.mdx @@ -121,6 +121,10 @@ The user receives an OTP and can verify control over the given email address. Users can change their phone number. The user receives an OTP and can verify control over the given phone number. +### Account deletion + +Users with the `user.self.delete` permission (granted via roles such as ORG_USER_SELF_MANAGER or SELF_MANAGEMENT_GLOBAL) can delete their own account. See our [guide on user self-deletion](/guides/manage/user/self-deletion) for details on how to build this into your application. + ### Identity providers Users can create a connection between a [local user account](#local-account) and an [external identity](#existing-identity--sso--social-login). diff --git a/apps/docs/content/guides/manage/console/administrators.mdx b/apps/docs/content/guides/manage/console/administrators.mdx index b6c94006f..f70e26206 100644 --- a/apps/docs/content/guides/manage/console/administrators.mdx +++ b/apps/docs/content/guides/manage/console/administrators.mdx @@ -47,6 +47,8 @@ In the right part of the management console you can find **ADMINISTRATORS** in t | Project Owner Global | PROJECT_OWNER_GLOBAL | Same as PROJECT_OWNER, but in the global organization. | | Project Owner Viewer Global | PROJECT_OWNER_VIEWER_GLOBAL | Same as PROJECT_OWNER_VIEWER, but in the global organization. | | Project Grant Owner | PROJECT_GRANT_OWNER | Same as PROJECT_OWNER but for a granted project. | +| Org User Self Manager | ORG_USER_SELF_MANAGER | Grants a user permission to read policies and delete their own account. | +| Self Management Global | SELF_MANAGEMENT_GLOBAL | Grants a user permission to create organizations, read policies, and delete their own account, in the global organization. | ## Configure roles diff --git a/apps/docs/content/guides/manage/user/self-deletion.mdx b/apps/docs/content/guides/manage/user/self-deletion.mdx new file mode 100644 index 000000000..6c2345049 --- /dev/null +++ b/apps/docs/content/guides/manage/user/self-deletion.mdx @@ -0,0 +1,48 @@ +--- +title: User Self-Deletion +description: "How to let authenticated users delete their own account via the ZITADEL User v2 API." +--- + +ZITADEL lets a user delete their own account. This is useful if you are building a "Delete my account" feature into your application, or if you need to comply with data deletion requests (e.g. GDPR right to erasure). + + +Self-deletion requires the `user.self.delete` permission, which is granted through roles such as [ORG_USER_SELF_MANAGER](/guides/manage/console/administrators) or SELF_MANAGEMENT_GLOBAL. A user without this permission cannot delete their own account. + + + +Deletion is permanent. Once a user is deleted, all authentication tokens are revoked, the user can no longer log in, and the operation cannot be undone. + + +## Delete the currently authenticated user + +Use the [Delete User](/reference/api/user/zitadel.user.v2.UserService.DeleteUser) endpoint from the User v2 API. The state of the user will be changed to `deleted`, the user will not be able to log in anymore, and endpoints requesting this user will return a "User not found" error. + +```bash +curl --request DELETE \ + --url ${CUSTOM_DOMAIN}/v2/users/{user_id} \ + --header 'Authorization: Bearer {token}' +``` + +Replace `{user_id}` with the ID of the user to delete and `{token}` with a valid access token. + +## Deleting via the ZITADEL Console + +ZITADEL's own Console UI (under _$CUSTOM_DOMAIN/ui/console/users/me_) also offers a **Delete Account** button on the user's own profile page. It calls the same User v2 `DeleteUser` endpoint described above, so it enforces the same `user.self.delete` permission requirement. + +## What happens after deletion + +* The user's state is set to `deleted`. +* All of the user's sessions and authentication tokens are invalidated. +* Subsequent requests referencing the user return a "User not found" error. +* The user can no longer authenticate against ZITADEL. + +## Building a "Delete my account" flow + +When integrating this into your own application: + +1. Require the user to be freshly authenticated (e.g. re-prompt for login or a second factor) before showing the delete option, since the action is irreversible. +2. Ask for explicit confirmation before calling the API. +3. Call the [Delete User](/reference/api/user/zitadel.user.v2.UserService.DeleteUser) endpoint using the user's own access token, scoped to their own `user_id`. +4. After a successful response, clear any local session state and log the user out of your application. + +If you need to retain a record of deletion requests for compliance purposes (e.g. GDPR/CCPA), log the request in your own application before calling the API. ZITADEL admins can still audit the deletion afterward via the [Event API](/guides/integrate/zitadel-apis/event-api). diff --git a/apps/docs/lib/sidebar-data.ts b/apps/docs/lib/sidebar-data.ts index b7d529493..1c4fb979c 100644 --- a/apps/docs/lib/sidebar-data.ts +++ b/apps/docs/lib/sidebar-data.ts @@ -582,6 +582,7 @@ export const guidesSidebar: readonly SidebarItem[] = [ collapsed: true, items: [ "guides/manage/user/reg-create-user", + "guides/manage/user/self-deletion", "guides/manage/terraform-provider", { type: "category",