Managing actor mappings

Link opaque actor IDs to a human-readable display name and/or email in the Matcher UI, then pseudonymize or delete mappings.

The Actor mappings page in the Matcher UI lets you associate opaque actor IDs with a human-readable display name and/or email. With the appropriate permissions, you can pseudonymize or delete mappings directly from the UI.

Accessing the Actor mappings page

---

Navigate to Matcher > Settings > Actor Mappings in the left sidebar.

To open this page, you need actor-mappings:read; administrators are also admitted. Without this access, Matcher redirects you to the main Matcher page. These checks apply only when authentication is enabled: with AUTH_PROVIDER=disabled, Matcher enforces no authentication or authorization, so the detail and edit operations can expose actor-mapping PII to anyone who can reach the deployment.

Browsing actor mappings

---

Figure 1. Actor mappings page.

The page uses cursor pagination and requests up to 20 mappings per UI page:

Column	Description
Actor ID	The opaque identifier maintained by Matcher
Created	Date and time the mapping was created
Updated	Date and time of the last update
Actions	Appears only when you may edit, pseudonymize, or delete; it contains only the buttons you are authorized to use

Type in the Actor ID prefix field to filter the table live — there is no separate search button. Use the Previous / Next buttons below the table to move through the available pages.

Display name and email do not appear in the table. Encrypted PII is loaded only when you open a mapping’s detail operations, such as editing.

Permissions

---

actor-mappings:read is the prerequisite for opening the page. Once you have that access, the header control and row actions are independently permission-gated:

• New mapping requires actor-mappings:write.
• Edit requires both actor-mappings:write and actor-mappings:deanonymize, because the edit sheet loads decrypted PII through the detail operation.
• Pseudonymize requires actor-mappings:pseudonymize.
• Delete requires actor-mappings:delete.

If you have none of the row-action permissions, the Actions column is omitted. Individual buttons for permissions you lack are hidden.

Creating an actor mapping

---

Click the New mapping button in the page header. The New actor mapping sheet opens with the following fields:

Field	Description
Actor ID	The opaque identifier (e.g. user:550e8400-e29b-41d4-a716-446655440000). Its maximum length is 255; longer values are rejected. Leading and trailing whitespace is automatically trimmed. It cannot be changed after creation.
Display name	The human-readable name (e.g. “John Doe”). Optional, but you must provide a Display name, an Email, or both.
Email	The email address (e.g. “[e-mail]”). Optional, but you must provide a Display name, an Email, or both. If supplied, it must be a valid email address.

Click Save.

Editing an actor mapping

---

Click Edit on a mapping row. The Edit actor mapping sheet opens with the current values pre-filled. The Actor ID field is locked — actor ID cannot be changed after creation; only the display name and email can be modified.

Leaving an existing Display name or Email field blank does not clear it: the UI omits blank values and the update preserves omitted stored values. The form also does not allow you to save when both fields are blank.

Click Save to apply changes.

Pseudonymizing an actor mapping

---

Click Pseudonymize on a mapping row. The Pseudonymize actor mapping? confirmation dialog warns that the action changes audit deanonymization behavior.

This operation replaces the display name and email with [REDACTED] while preserving the actor ID link. The UI has no dedicated undo action, and the original values are not restored automatically. A user with both write and deanonymize permission can later edit the mapping and manually enter replacement values.

Click Pseudonymize to proceed.

Deleting an actor mapping

---

Click Delete on a mapping row. The Delete actor mapping? confirmation dialog warns that the action changes audit deanonymization behavior.

Click Delete to proceed.

Deletion permanently removes the mapping between the opaque actor ID and its stored display name and email. Assess any legal or retention obligation in your deployment separately.