Adding a ‘Delete My Account’ Button in Keycloak

Last updated: July 2026

Keycloak ships a built-in “Delete Account” Application-Initiated Action that surfaces a self-service delete button inside the Account Console, but it is disabled by default and the official documentation buries the enabling steps. To activate it you need to do two things: enable the delete_account required action under Authentication > Required Actions, and grant the delete-account client role (on the account client) to the users who should be permitted to delete themselves. Miss either step and the button either never appears or produces a 403 error. This post walks through both steps, explains what data Keycloak actually removes when a user deletes their account, and covers the GDPR right-to-erasure implications you need to be aware of before enabling this feature in production.

What is the delete_account action in Keycloak?

Keycloak 17 introduced a built-in Application-Initiated Action (AIA) called delete_account. Unlike most required actions — which are triggered during the login flow — this one is initiated from inside the Account Console. When both enabling conditions are met, a “Delete account” button appears in the Account Console under Personal Info. The user clicks it, re-authenticates to confirm their identity, and Keycloak permanently deletes their user record.

The feature is designed precisely for GDPR Article 17 (“right to erasure”) compliance workflows: rather than routing a deletion request through a support ticket or a manual admin operation, users can exercise their own right-to-erasure directly. That matters for both compliance and user trust — and reduces operational overhead for your team.

Before enabling it, though, you need to understand exactly what “deleted” means in Keycloak’s data model, and who you are granting this power to. Both of those topics are covered below after the setup steps.

Step-by-step: enabling self-service account deletion

Step 1 — Enable the delete_account required action

The delete_account required action ships disabled in every realm, including new ones. Enable it per realm:

1. In the Admin Console, select your realm from the top-left dropdown.
2. Navigate to Authentication > Required Actions.
3. Find Delete Account in the list.
4. Toggle the Enabled switch to On.
5. Leave Default Action toggled Off (explained in the scoping section below).
6. Click Save.

The required action is now registered, but users still cannot trigger it. You also need to grant them the client role that permits deletion.

Step 2 — Grant the delete-account client role

Keycloak enforces an authorization check before it will honor a deletion request. The account client (the built-in client that backs the Account Console) has a role named delete-account. A user must hold this role — either directly or via a group or composite role — for the delete button to function.

Option A: Assign to a specific user (recommended for initial testing)

1. Navigate to Users and open the target user.
2. Go to the Role Mapping tab.
3. Click Assign Role.
4. In the filter dropdown, switch from Filter by realm roles to Filter by clients.
5. Select the account client from the list.
6. Check delete-account and click Assign.

Option B: Add to default roles (grants all realm users the ability to delete themselves)

1. Navigate to Realm Settings > User Registration > Default Roles.
2. In the client roles section, select the account client.
3. Move delete-account from available to assigned.

Use Option B only after careful deliberation. It grants every user in the realm the ability to permanently delete their own account, with no admin approval step. For many B2C applications this is the intended behavior; for B2B or internal workforce applications it carries higher risk.

Checklist: both steps must be complete

How the user experience works

Once both steps are complete, the flow from the user’s perspective is straightforward:

1. The user logs in and navigates to the Account Console (/realms/{realm}/account/).
2. Under Personal Info, a Delete account link appears at the bottom of the page.
3. The user clicks the link. Keycloak immediately redirects them to a re-authentication step — they must enter their password (and any required second factor) to confirm the deletion.
4. After successful re-authentication, Keycloak deletes the user record and redirects them to the post-logout URL configured on the realm.

The re-authentication step is not configurable — it is hardcoded into the action to prevent accidental or coerced deletions. This is the correct behavior from a security standpoint and also satisfies the GDPR requirement that erasure requests must be confirmed by the data subject.

Scoping who can delete their account

The two options described above — per-user role assignment versus default roles — represent opposite ends of a spectrum. In practice, most applications land somewhere between them.

Per-user assignment is appropriate when you want to enable deletion only for users who have completed an off-boarding workflow, accepted a data-export notification, or been verified through a support channel. You can automate the role grant programmatically via the Admin REST API.

Group-based assignment is a middle path: create a group that holds the delete-account client role, and add users to that group when they are eligible to self-delete. This is cleaner than per-user assignment at scale and easier to audit.

Default roles are appropriate for consumer-facing applications where self-service account management is a core product promise and the deletion consequence is well understood.

Do not enable Default Action alongside the role grant. If “Default Action” is enabled on the required action, Keycloak will prompt every new user to delete their account during registration — which is the opposite of what you want. The Default Action checkbox is for actions that should fire on first login (like agreeing to terms of service). For delete_account, leave it off.

If you want to restrict deletion further — for example, only allow deletion after a 30-day waiting period — you will need a custom authentication flow. The built-in AIA does not have a waiting-period mechanism. See our post on building custom authentication flows in Keycloak for the extension points available.

What data does Keycloak actually delete?

This is the question that matters most for GDPR compliance, and the answer requires precision.

When a user is deleted through the delete_account action — or through the Admin REST API DELETE call described in the next section — Keycloak removes:

• The user record from the USER_ENTITY table (email, username, first name, last name, enabled status, etc.)
• All user attributes stored in USER_ATTRIBUTE
• All role mappings
• All group memberships
• All active sessions and offline tokens associated with the user
• Consent records for client applications

Keycloak does not automatically delete:

• Admin event log entries — if you have admin events enabled, the event records for actions performed by or on this user remain in ADMIN_EVENT_ENTITY
• User event log entries — login events, failed authentication events, and other user events in EVENT_ENTITY remain until they expire based on your realm’s event retention configuration
• External data — anything your application stored in its own database using the Keycloak user ID as a foreign key is unaffected

This distinction matters for GDPR. Keycloak’s event retention is configured under Realm Settings > Events > User events expiration. If your compliance posture requires that audit logs are also purged on erasure, you must handle that separately — either by shortening the retention window or by implementing a post-deletion cleanup step in your application layer.

For a comprehensive treatment of Keycloak data retention and GDPR erasure obligations, see our dedicated guide on Keycloak GDPR data erasure and retention. The current post focuses on the self-service UX mechanism; that post covers the operational and compliance-side processes.

Keycloak’s event logging system is also worth understanding independently — the complete guide to Keycloak auditing and event logging explains what is captured, how to configure retention, and how to forward events to external SIEMs.

Admin API deletion for comparison

The Account Console self-service flow is convenient for users, but sometimes you need to trigger deletion programmatically — for example, as part of an off-boarding workflow, a GDPR erasure API your application exposes, or a bulk cleanup script.

The Admin REST API DELETE endpoint for a user is:

DELETE /admin/realms/{realm}/users/{userId}
Authorization: Bearer {admin-access-token}

Here is a minimal example using curl:

# 1. Get an admin access token
TOKEN=$(curl -s -X POST 
  "https://your-keycloak.example.com/realms/master/protocol/openid-connect/token" 
  -d "client_id=admin-cli" 
  -d "username=admin" 
  -d "password=YOUR_PASSWORD" 
  -d "grant_type=password" 
  | jq -r '.access_token')

# 2. Delete the user
curl -s -X DELETE 
  "https://your-keycloak.example.com/admin/realms/myrealm/users/USER_UUID" 
  -H "Authorization: Bearer $TOKEN" 
  -w "%{http_code}"

A successful deletion returns HTTP 204 No Content. The same data-removal rules apply: user record and sessions are removed, event logs are not.

If you are building an erasure workflow into your application, combining the Admin API call with a cleanup of your own application’s data (any tables that reference the Keycloak user ID) is the correct pattern. You can also extend this by using custom user attributes in Keycloak OIDC tokens to propagate a deletion_requested_at attribute as part of an approval workflow before the final delete is issued.

GDPR right-to-erasure framing

GDPR Article 17 grants data subjects the right to request erasure of personal data without undue delay when, among other grounds, the data is no longer necessary for the purpose for which it was collected, or the subject withdraws consent. For most web applications, the user’s account record in Keycloak constitutes personal data: it contains at minimum an email address.

Enabling self-service account deletion in Keycloak directly fulfills the “without undue delay” requirement by making erasure immediate and user-initiated. It also satisfies the requirement that erasure be easy to request — the button is in the Account Console, not buried in a support form.

However, self-service deletion alone is not a complete GDPR erasure implementation:

1. Event logs: As noted above, Keycloak retains event logs until they expire. Configure your retention window to match your data retention policy.
2. Downstream systems: Any system that received the user’s ID or profile data via a token or webhook must also perform erasure. Keycloak cannot orchestrate that.
3. Backups: Point-in-time database backups contain historical user records. Your erasure policy should address backup retention.
4. Right-to-erasure log: Some interpretations of GDPR require that you retain a pseudonymous record that an erasure occurred (so you can demonstrate compliance), even after the personal data is gone. This is a legal question; discuss it with your DPO.

Keycloak’s built-in delete_account action is the right starting point — it handles the identity-layer erasure cleanly. Building a complete erasure pipeline around it is the rest of the work.

If you are managing Keycloak audit logs for compliance purposes, our guide on Keycloak auditing best practices for security covers the configuration options available.

Alternatives to self-service deletion

Not every application should enable self-service account deletion. If you decide against it, here are the alternatives:

Admin-side deletion via the Admin Console

An administrator navigates to Users, finds the user, opens their profile, and clicks Delete. This works but does not scale and introduces a support burden.

Admin-side deletion via the Admin REST API

Described in the section above. Suitable when deletion is triggered programmatically by your application as part of a request workflow.

Custom Authentication Flow with approval gate

If you want to offer self-service deletion but require a delay or approval step, you can build a custom AIA that sets a marker attribute (deletion_requested_at) and then a scheduled job that performs the actual deletion after a cooling-off period. This is more complex but gives you a cancellation window. For the extension approach, see the Keycloak custom authentication flows guide.

Disable the Account Console entirely

If your application provides its own profile management UI, you can disable the Account Console and handle deletion through your own UX backed by the Admin API. This gives you full control over the flow and the confirmation copy shown to users.

Getting started with Keycloak

If you are new to Keycloak and this is one of the first features you are configuring, the Keycloak getting started guide for 2026 covers realm setup, client configuration, and the admin console navigation you will need before following the steps above.

Frequently asked questions

How do I let users delete their own account in Keycloak?

Enable the delete_account required action under Authentication > Required Actions in the Admin Console, then assign the delete-account role from the account client to each user (or add it to default realm roles for all users). Once both are in place, a delete button appears in the Account Console under Personal Info. The user must re-authenticate before the deletion is processed.

What is the delete_account action in Keycloak?

delete_account is a built-in Application-Initiated Action introduced in Keycloak 17. Unlike required actions that fire during login, it is triggered by the user from within the Account Console. When enabled and authorized, it allows a user to permanently delete their own realm account including their profile, sessions, and role assignments. It is disabled by default in every realm and requires an explicit opt-in by the administrator.

Does deleting a Keycloak user remove all their data?

Not completely. Keycloak removes the user entity, attributes, sessions, offline tokens, role mappings, group memberships, and consent records. It does not remove user event log entries or admin event log entries — those persist until they expire according to the realm’s event retention settings. Any data your application stored using the Keycloak user ID as a reference must be deleted separately, as Keycloak has no visibility into external databases.

Can I restrict which users are allowed to delete their account?

Yes. The safest approach is to assign the delete-account client role only to specific users or to a group, rather than adding it to default roles. You can also revoke the role programmatically via the Admin REST API as part of a workflow — for example, preventing deletion while a user has an active subscription.

Is self-service account deletion enough for GDPR compliance?

It covers the identity-layer erasure for data held in Keycloak itself: the user record and sessions. A complete GDPR Article 17 compliance implementation also requires purging the user’s data from your own application databases, addressing any third-party systems that received the user’s profile data via tokens or webhooks, and reviewing backup retention policies. Keycloak’s delete_account action is the right starting point, but it is one piece of a broader data erasure pipeline.

Conclusion

Keycloak’s built-in delete_account Application-Initiated Action is the cleanest way to offer users a self-service path to delete their own account. Enabling it takes two steps — toggling the required action on in the realm and granting the delete-account client role to eligible users — and produces a confirmation-gated delete flow in the Account Console without any custom code.

Key points to carry forward:

• Both the required action and the client role assignment are mandatory; either alone is insufficient.
• Do not add delete-account to default roles without deliberate consideration of who that grants deletion rights to.
• Keycloak removes user records and sessions on deletion, but event log entries persist until expiry — plan your retention configuration accordingly.
• Self-service deletion fulfills the immediate-erasure requirement under GDPR Article 17 for data Keycloak holds, but downstream systems require separate handling.

If you would rather not manage this configuration yourself, Skycloak’s managed Keycloak platform handles the infrastructure so your team can focus on the application logic. See the Skycloak plans and pricing to find the tier that fits your team.