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.
What does not exist
Section titled “What does not exist”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.
Who decides what
Section titled “Who decides what”| 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 needsidentity_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.
2. Erase an end user
Section titled “2. Erase an end user”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-erasuresGET /api/v1/applications/{application_id}/identity-erasures/{job_id}POST /api/v1/applications/{application_id}/identity-erasures/{job_id}/resumeIf 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 |
3. Erase a platform user
Section titled “3. Erase a platform user”Self-erasure needs a recent sign-in. A tenant administrator can erase a member of the tenant:
POST /api/v1/users/{user_id}/erasureGET /api/v1/users/{user_id}/erasurePOST /api/v1/users/{user_id}/erasure/resumeDELETE /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.
4. Close a tenant
Section titled “4. Close a tenant”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}/closureGET /api/v1/tenants/{tenant_id}/closurePOST /api/v1/tenants/{tenant_id}/closure/waive-export-windowThe 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.
5. Say only what is true
Section titled “5. Say only what is true”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
detachorretain. - 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.
Availability
Section titled “Availability”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.
