Account Deletion

Autentico supports user-initiated account deletion with two modes: immediate self-service deletion and admin-reviewed deletion requests.

Deletion modes

Self-service deletion

When allow_self_service_deletion is true, accounts with a local password can be deleted immediately after confirming the current password. The account UI asks for it, and API callers must send current_password. Password failures use the shared account lockout policy, with attempts counted atomically across concurrent requests. The POST endpoint also uses the configured per-IP authentication rate limits. A successful deletion records a user_deleted audit event with source: self when audit logging is enabled.

Admin-reviewed deletion

When allow_self_service_deletion is false (the default), the user’s request is stored as a pending deletion request. An admin must review and approve or cancel the request. Accounts without a local password, including passkey-only and federated accounts, also use this review flow even when immediate self-service deletion is enabled. Submitting a request does not require a password and leaves the account active.

Configuration

curl -X PUT https://auth.example.com/admin/api/settings \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"allow_self_service_deletion": "true"}'

Setting	Default	Description
`allow_self_service_deletion`	`false`	When `true`, password accounts can delete immediately with current-password confirmation; passwordless accounts require admin review

Account API endpoints (user-facing)

These endpoints are authenticated with the user’s access token.

Request deletion

POST /account/api/deletion-request

Submits a deletion request. Eligible password accounts are deleted immediately after current-password confirmation (returns 204). Admin-review mode and passwordless accounts create a pending request (returns 201). API clients should use the response status to distinguish the outcomes.

curl -X POST https://auth.example.com/account/api/deletion-request \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "No longer using the service", "current_password": "YOUR_PASSWORD"}'

Field	Required	Description
`reason`	No	Optional reason for the deletion request
`current_password`	For immediate deletion	Current local password; never stored in the request or audit record

Missing or malformed current-password input, trailing data, or a second JSON value returns 400; an incorrect password returns 403, and account lockout or IP throttling returns 429. These responses preserve the account and sessions. Immediately before deletion, the server rechecks the confirmed password hash, account status, and caller token/session inside the deletion transaction. A password reset, account deactivation, logout, or token revocation that commits first prevents deletion and requires signing in again (401). The account profile API includes has_password so clients can display the appropriate deletion flow.

Returns 409 Conflict if a pending request already exists, or last_active_admin if immediate deletion would remove the last active administrator. Create or promote another active administrator first.

Get deletion request status

GET /account/api/deletion-request

Returns the current user’s pending deletion request, or null if none exists.

curl https://auth.example.com/account/api/deletion-request \
  -H "Authorization: Bearer $USER_TOKEN"

Cancel deletion request

DELETE /account/api/deletion-request

Cancels the current user’s pending deletion request.

curl -X DELETE https://auth.example.com/account/api/deletion-request \
  -H "Authorization: Bearer $USER_TOKEN"

Returns 204 on success, 404 if no pending request exists.

Admin API endpoints

These endpoints require admin authentication.

List deletion requests

GET /admin/api/deletion-requests

Lists all pending deletion requests with pagination, sorting, search, and date filtering.

curl https://auth.example.com/admin/api/deletion-requests \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Parameter	Description
`sort`	Sort field: `requested_at` (default), `username`, `email`
`order`	Sort order: `asc` (default), `desc`
`search`	Search by username, email, or reason
`requested_at_from`	Filter: requested at or after (ISO 8601)
`requested_at_to`	Filter: requested at or before (ISO 8601)
`limit`	Max results per page (1–100, default 100)
`offset`	Number of results to skip (default 0)

Approve deletion

POST /admin/api/deletion-requests/{id}/approve

Permanently deletes the user and all associated data.

curl -X POST https://auth.example.com/admin/api/deletion-requests/$REQUEST_ID/approve \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Returns 204 on success. Logs a deletion_approved audit event. Returns 409 Conflict with last_active_admin if the target is the last active administrator; the account and pending request are preserved.

Cancel (dismiss) deletion request

DELETE /admin/api/deletion-requests/{id}

Cancels a deletion request without deleting the user.

curl -X DELETE https://auth.example.com/admin/api/deletion-requests/$REQUEST_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

What gets deleted

When a deletion is approved (or executed in self-service mode), the user and all associated data are permanently removed:

User account record
All OAuth sessions
All IdP sessions
All access and refresh tokens
All MFA challenges and TOTP secrets
All passkey credentials
All trusted device tokens
All federated identity links
All group memberships
All consent records
Password reset and magic-link tokens
Device authorization codes
The deletion request itself

Database table

The deletion_requests table stores pending requests:

Column	Type	Description
`id`	TEXT	Primary key (xid)
`user_id`	TEXT	Foreign key to `users.id`
`reason`	TEXT	Optional reason (nullable)
`requested_at`	DATETIME	When the request was submitted