> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
***
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. "[john.doe@example.com](mailto:john.doe@example.com)"). 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.