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 <[email protected]>
This commit is contained in:
Rajat Singh
2026-07-16 16:35:44 +00:00
committed by GitHub
co-authored by Rajat Singh
parent 75bc058bce
commit 94ac4237a9
4 changed files with 55 additions and 0 deletions
@@ -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).
@@ -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
@@ -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).
<Callout>
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.
</Callout>
<Callout>
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.
</Callout>
## 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).
+1
View File
@@ -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",