Purge entities
What is a purge entity?
A purge entity is a short-lived, null-data marker that records the deletion of a user entity. It preserves just enough information to answer one question after the fact: what was deleted, and where did it live?
Purge entities are retained for 30 days after the deletion, after which they are removed permanently. Systems that synchronize deletions must poll the purge collection within that window.
For GDPR compliance, Vault cannot retain the data of entities that linked applications mark as deleted. The delete itself is hard — the original entity is removed along with its data — while the purge entity remains as a tombstone that other systems can query to synchronize their own deletions. Note that it is the developer’s responsibility to wire their application’s delete flow to Vault’s purge API.
Vault performs the deletion, but does not propagate it to your other systems. Purge entities exist precisely so you can build that propagation yourself: query the purge collection, learn what was deleted, and mirror the deletion where your architecture requires it.
Purge entity anatomy
| Field | Meaning | Type | Nullable |
|---|---|---|---|
entity |
The former entity’s id (primary key) | uuid |
false |
entityOid |
The former entity’s ObjectId, if it had one | bson |
true |
realm |
The realm the entity used to belong to | uuid |
false |
Who can purge users?
Users can be purged three ways:
- By the account holder (platform owner)
- By the user themselves, completing the delete flow through the OAuth gateway
- By a client application, calling the purge API on the user’s behalf
Deleting via the OAuth gateway
The OAuth gateway exposes a complete flow through which a user can delete their own account.
Completing the delete user flow hard removes the user entity from Vault. This cannot be undone.
Deleting via the API
If a client application receives a request from a user who wants to delete their account, it can call Vault’s purge API on the user’s behalf. The call is authenticated with the user’s own access token — meaning the deletion is authorized by the user, not by the client’s credentials.
| Property | Value |
|---|---|
| Method | DELETE |
| Path | /api/v1/user |
Authentication:
| Header | Value |
|---|---|
Authorization |
Bearer <access_token> |
Response:
The removed user entity.
Because the request carries the user’s token, Vault identifies the user to purge from the token itself — no user id is passed in the request.
Making this call hard removes the entity from Vault. This cannot be undone.
Synchronize deletions
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/user/purge |
Body parameters:
| Parameter | Required | Description |
|---|---|---|
clientId |
Yes | The client’s public identifier |
clientSecret |
Yes | The client’s secret |
Response:
The realm’s purge entity collection — an array of tombstones for users deleted within the 30-day retention window. Each entry contains:
entity— the former user’s identityOid— the former user’s ObjectId, if applicablerealm— the realm the user belonged to
Use this endpoint to synchronize deletions across your systems: fetch the collection, compare against your local records, and mirror the deletions where required.
Purge entities are retained for 30 days after deletion, after which they are removed permanently. Poll this endpoint frequently enough to catch all purges before they expire.