Skip to content

Handle a personal-data erasure request

When someone asks you to delete their data, the platform does the erasing and you make the decisions. An erasure runs as a durable job that stops the person’s credentials first, removes their data, and reports completed only after every surface checks clean. This recipe covers the requests a builder or tenant administrator can carry out.

There is no consumer endpoint for erasure and no page-builder action that starts one. A signed-in end user cannot erase themselves, and no form, block or rule triggers a job. Do not publish a “delete my account” button that implies otherwise. Take the request through your own support channel, confirm who is asking, and then act on it as a builder.

The person asking Who decides How it is carried out
An end user of your application You, as the controller of your application’s data Delete their identity record (step 2)
A member of your tenant Themselves or a tenant administrator Erase the platform user (step 3)
An end user who writes to MERO You; MERO refers the request to you Delete their identity record (step 2)
Your whole organisation is leaving A tenant administrator or MERO Close the tenant (step 4)

1. Decide what happens to the records they created

Section titled “1. Decide what happens to the records they created”

Set settings.platform.identity_erasure on each model whose records an end user can create:

  • delete: the records go with the person.
  • detach: the records stay and keep a reference that now resolves to nothing. Use this only when the rest of the record holds no personal data.
  • retain: the records stay untouched. It needs identity_erasure_basis, your reason in at most 200 characters, and you are answerable for it as the controller.

A model with no setting blocks the job until you choose, and nothing in that model is deleted while it waits. Choosing before the first request keeps erasure from stalling.

Delete the identity record through the records API. It needs records:delete in the identity’s workspace:

DELETE /api/v1/records/{record_id}

The answer is 202 with the job, not 204, and the record stays until the job removes it. MCP and Public API deletes of an identity open the same job. Then follow it:

GET /api/v1/applications/{application_id}/identity-erasures
GET /api/v1/applications/{application_id}/identity-erasures/{job_id}
POST /api/v1/applications/{application_id}/identity-erasures/{job_id}/resume

If the job is blocked, fix what its blockers name and resume it:

Blocker What to do
undeclared_erasure_policy Choose a policy for the model (step 1)
reference_prevents Change the field’s on_delete, or remove the referencing records
cross_workspace_copy Remove the reference from the other workspace or application
shared_personal_content, file_discovery_incomplete Decide each file with a file_resolutions entry on resume
object_deletion_unconfirmed Have an operator inspect storage, then resume
missing_discovery_coverage Repair the session field mappings, then resume

Self-erasure needs a recent sign-in. A tenant administrator can erase a member of the tenant:

POST /api/v1/users/{user_id}/erasure
GET /api/v1/users/{user_id}/erasure
POST /api/v1/users/{user_id}/erasure/resume

DELETE /users/{user_id} only deactivates, so it does not satisfy an erasure request. The platform never picks a successor. A last owner blocks with last_owner until a person assigns another tenant_admin, and a sole member blocks with sole_member_tenant until the tenant is closed. A billing contact blocks until the billing email changes.

Archive the tenant first. Archiving alone deletes nothing and starts no clock, whether a person or a billing event did it. Deletion is scheduled only by an explicit request from a tenant administrator with a recent sign-in, or from a platform owner:

POST /api/v1/tenants/{tenant_id}/closure
GET /api/v1/tenants/{tenant_id}/closure
POST /api/v1/tenants/{tenant_id}/closure/waive-export-window

The closure records its timestamp and deadlines:

Deadline When What happens
export_ends_at 30 days after the request Export keeps working until now, and nothing is deleted
purge_deadline_at 30 days after the export window ends The latest date by which the purge should finish; it usually finishes much sooner, and an alert fires if it does not
account_data_deadline_at 90 days after the request The end of the policy’s Account Data period
tombstone_sweep_due_at 90 days after the purge completes Remaining account placeholders nothing refers to are deleted
retained_review_at Seven years after the request Someone reviews what billing retention kept; nothing is deleted automatically

Export each application before the window ends with GET /api/v1/applications/{application_id}/export. An exported bundle is your copy and is outside the platform’s reach afterwards. Only a tenant administrator can waive the export window, because the export is the Customer’s to give up. A waiver cannot be undone.

The purge erases every identity and every user that belongs only to this tenant, then the tenant’s remaining rows and every object it owns. An account that also belongs to another tenant keeps existing and only loses its access here.

Report what the job or closure’s own read model reports. Use “profile data erased and credentials revoked”, not “anonymized” or “everything deleted”. These remain after a successful erasure:

  • Pseudonymous ids on retained audit rows. They point at nothing identifying, but they still link to each other.
  • Legal acceptance evidence, including the email address, IP address and user agent at acceptance.
  • Billing, invoice and tax records for seven years. The billing email is redacted at closure.
  • Records you chose to detach or retain.
  • Backups, until they age out. Backups are kept by count, so one can outlast seven days when runs are missed. A restore replays recorded erasures before the service takes traffic.

A platform owner can hold one workspace or one account back from a closure on legal, security, fraud-prevention or dispute grounds. That hold has a stated basis and an end date within a year. A closure’s statement lists each hold with personal_data_may_remain: true, and it sets complete_erasure_claimed to false in every state. Do not tell the person their data is gone while a hold covers it.

These routes answer 503 until a deployment has provisioned ERASURE_LEDGER_BUCKET and ERASURE_EMAIL_HMAC_KEY, and nothing is removed in that state. Identity deletion never falls back to a plain delete.