mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-20 11:58:47 +00:00
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:
co-authored by
Rajat Singh
parent
75bc058bce
commit
94ac4237a9
@@ -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).
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user