PII and Data Governance
Ema can detect personally identifiable information (PII) in the content it processes and apply a masking policy before that content is shown to a user or sent to an external model or integration. As a workspace admin you control two things: how detected data appears to people inside Ema, and what detected data is allowed to leave Ema for LLMs and third-party integrations.
These controls live on the PII Management tab at /admin/governance/pii, alongside the audit log.
Enabled per workspace. PII governance is gated by the pii_masking feature flag. When it is off, the PII Management tab is hidden and the Governance page shows only the audit log. If you don't see the tab, the feature isn't turned on for your workspace. Contact your Ema representative.
Who can manage PII policy. PII governance is a system_admin surface. The PII access log is restricted to system_admin as well. See the audit log.
How detection works
Ema classifies detected data into a fixed taxonomy of entity types (for example EMAIL_ADDRESS, US_SOCIAL_SECURITY_NUMBER, CREDIT_CARD_NUMBER, PERSON_NAME). Each entity type belongs to one or more categories: financial, credentials, healthcare, personal, government, device, or protected. The taxonomy follows the Google Cloud DLP infoType naming convention (UPPER_SNAKE_CASE), which aligns with common compliance references.
When PII is detected, Ema can replace it with a stable pseudonym token (for example PERSON_48291037 or EMAIL_73920156) that can be reversed back to the original only where policy permits.
Display levels
Each entity type has a display level that determines how a detected value is shown to users inside Ema. There are four levels, from most to least restrictive:
| Level | UI label | What the user sees | Example |
|---|---|---|---|
full_mask | Fully Masked | The value is hidden entirely. | — |
pseudonym | Pseudonym Only | A stable, non-reversible token. | SSN_61038472 |
partial | Partial (last 4) | A redacted form revealing only a tail or fragment. | ***-**-6789 |
original | Show Original | The cleartext value. | 123-45-6789 |
System ceilings
Every entity type has a system maximum (the most permissive display level you are allowed to choose). You can set a display level at or below the ceiling, never above it. The ceilings are fixed by the platform and reflect regulatory baselines (HIPAA Safe Harbor, PCI DSS, NIST SP 800-122, GDPR, CCPA). For example:
- Secrets and credentials (passwords, API keys, JWTs, SSH keys) are capped at Fully Masked. Even a
system_admincannot reveal any portion. - Financial and government identifiers (SSN, credit card number, passport) are capped at Partial. You may reveal the last few digits but never the full value.
- Names and organization names allow Show Original because they are routinely needed in business context.
When an entity type's ceiling is Fully Masked, its display control is locked and cannot be changed.
Setting a display level
On the Display Policy card, each detected entity type has a dropdown listing only the levels allowed for it (up to its ceiling), each annotated with an example of what the result looks like. Choose a level and it saves immediately. The default display level for most sensitive types is Fully Masked.
Sharing policy (integration egress)
The Sharing Policy card controls what detected data is allowed to leave Ema in cleartext for external LLMs and integrations. Each entity type has one of three states:
- Always sent. A small baseline set of business-context entities is always allowed to egress:
PERSON_NAME,EMAIL_ADDRESS,ORGANIZATION_NAME,PHONE_NUMBER,STREET_ADDRESS,EMPLOYMENT_INFORMATION, andEDUCATION_INFORMATION. These show a green Always sent badge and cannot be toggled. - Never sent. Sensitive types (all credentials, financial identifiers, healthcare data, government IDs, device identifiers, and protected attributes) are hard-locked against cleartext egress. They show a red Never sent badge and cannot be toggled. When such a value must reach a model, it crosses the boundary as a pseudonym token, never as cleartext.
- Configurable. Any remaining entity type defaults to not sent (tokenized) and can be switched on with a toggle. There is no implicit grant. You opt each one in deliberately.
Egress locks are absolute. Entity types marked Never sent must never cross an external LLM vendor boundary in cleartext, regardless of workspace configuration. This is a platform-level guarantee, not a workspace preference.
Data lifecycle
The retention orchestrator manages the full data lifecycle across all platform services, including the LLM gateway's two append-only tables. Both tables are purged by the retention service on time-based expiry, workspace churn, and data subject erasure requests.
| Data type | Table | Default retention | Included in data subject erasure |
|---|---|---|---|
llm_token_usage | llmgateway.token_usage | 365 days | No. Holds foreign-key UUIDs and token counts only, no free text. |
llm_request_log | llmgateway.request_response_logs | 90 days | Yes. error_message can contain provider error text that quotes a prompt. |
Both tables are workspace-scoped and carry no AI Employee column. A purge request scoped to a single AI Employee is refused rather than silently widened to the whole workspace. The retention service owns the windows and the triggers; the LLM gateway only deletes rows it is instructed to remove.
Legal holds and audit retention
A legal hold freezes a workspace's audit events for litigation or investigation. While a hold is active, the platform's audit retention purge will not delete any events for that workspace, even if they have passed their normal retention window.
The behavior is fail-closed: if the platform cannot confirm whether a hold is active (for example, because of a temporary service disruption), the purge is also skipped for that workspace. Keeping events past their window is recoverable; deleting them under a hold is not. A hold on one workspace does not affect the purge schedule for any other workspace.
Purge does not resume automatically on hold release. The retention sweep runs on a daily cycle. Events that were preserved under a hold are purged on the next sweep after the hold is released, provided their retention window has passed.
Reference
The PII service backs these surfaces. The display-policy dropdowns read and write per-entity overrides; the sharing toggles read and write the workspace egress policy.
| Action | Endpoint |
|---|---|
| List per-entity display overrides | GET /tenant-config |
| Set an entity's display level | PUT /tenant-config |
| List egress (sharing) policy rows | GET /tenant-egress-policy |
| Set an entity's egress allowance | PUT /tenant-egress-policy |
| Revert an egress row to default | DELETE /tenant-egress-policy |
Every PII decision (what was tokenized, partially masked, redacted, or passed through, and at which boundary) is recorded for compliance. See the PII access log.
What's next
- Audit log — review the PII access log and the full event history.
- Governance and permissions — the roles that can manage governance.
- Workspace management and SSO — configure model providers that data egresses to.