Pseudonymous Principals and Erasure
While the evidence vault is on, new audit events do not carry email addresses or free-text comments. They carry an opaque pseudonym for the person instead. The link from the pseudonym to the person is stored in one place, so a super_admin can remove it. This page describes what changes, and the steps to unlink a person.
None of this is legal advice. It describes technical controls and their limits. Whether it meets an obligation in your situation is for you and your advisers to decide.
What changes in new events
This applies only to events recorded after the vault was turned on, and only while it stays on. Events recorded before are never rewritten.
| Event data | Without the vault | With the vault on |
|---|---|---|
Approval recipients, in the audit event of an approval-required decision and in approval.pending | The email addresses | recipientPseudonyms: one pseudonym per recipient who is a member of your organization, and recipientCount. An address that is not a member is counted and not recorded |
| An approver's comment, in the approve, reject and revoke events | The comment text | commentDigest (sha256: of the text) and commentLength. The text stays only on the approval itself |
Unchanged: user ids in events, the approval notification and its email, webhook bodies, and what the approval API returns. Those need the real values to do their job.
A pseudonym is an opaque id (pnm_ and 32 hex characters), one for each user of each organization. It is created the first time an event needs it.
Find or resolve a pseudonym
All the routes on this page need a signed-in super_admin and the evidence.vault entitlement. API keys are refused.
| Route | Returns |
|---|---|
GET /v1/principals?user_id=... | The pseudonym of that member of your organization. 404 if there is none yet, or it was erased |
GET /v1/principals/{pseudonym} | { version, pseudonym, user_id, created_at, erased_at }. user_id is null once erased. Another organization's or an unknown pseudonym is 404 |
Unlinking a person
Do the steps in this order. After step 5 the references can no longer be listed.
- Deactivate the member. An active member cannot be erased (
409principal_active). - Find the pseudonym with
GET /v1/principals?user_id=.... - List the vault references:
GET /v1/principals/{pseudonym}/vault-refs. It returns the claimed pointers of decisions and outcomes whose authenticated principal is that user, newest first (limitup to 200 andoffset), andkey_refs, the distinct key references over all of them, not only the page. Calls made with an API key are not linked to a person, so they never appear here. If your enforcement points mostly use API keys, this list can be short or empty; use your own records of which key protects which principal group. - Destroy the keys in your key service. OpenProdkt never holds a key and never calls your key service, so this step is yours. Cloud key services delete after a waiting period (AWS KMS: 7 to 30 days), and a key that is disabled or pending deletion already cannot decrypt. Until deletion completes, the records are still recoverable by anyone who can re-enable the key.
- Erase the pseudonym:
POST /v1/principals/{pseudonym}/erase. - Check:
GET /v1/principals/{pseudonym}now showsuser_id: nullanderased_at, and the audit trail has aprincipal.erasedevent.
What erase does
In one transaction it:
- removes the link from the pseudonym to the person. The row stays as a record that the pseudonym was erased,
- clears the comment text of approvals that person reviewed in your organization,
- records
principal.erasedwith the pseudonym, the time and thesuper_adminwho did it.
Repeating it changes nothing and answers 200. A member who is reactivated later gets a new pseudonym.
What erase does not do
- It does not destroy a key. OpenProdkt cannot, and its record that you erased a pseudonym is not evidence that your keys are gone.
- It does not delete the account. The user, their role and their API keys are unchanged, and so are user ids that appear in existing events. A user id is neither a name nor an address, but it identifies the account while the account exists.
- It does not rewrite events. Events from before the vault was on keep the data they hold, and so do their exports. Events recorded afterwards keep the pseudonym, which no longer leads to a person.
- It does not delete the encrypted records. They stay in your storage, readable or not depending on your keys.
- It does not remove the comment digests. The audit events keep
commentDigestandcommentLength. A digest of a short or predictable comment, such asapproved, can be confirmed by guessing the text.
Limits
- The vault and the pseudonyms are technical controls, not a statement that an erasure, retention or privacy obligation is met.
- Pseudonyms cover approval recipients and comments. Other places where a person's data may appear, such as your own webhook receivers, mail logs or Console sessions, are outside this feature.
- Only a deactivated member can be erased.