Masking tokens

What an agent receives ​

For a field that holds personal data, the server replaces the value with a token built from the field name and a counter, such as EMAIL_1, NAME_2 or CONTACT_EMAIL_7. Fields in a sensitive data class are left out and named in denied (REST) or withheld_fields (MCP).

{
  "denied": ["party.tax_id"],
  "value": { "email": "EMAIL_4", "id": "01a14650-2667-...", "name": "NAME_5", "notes": "NOTES_6" }
}

Rules of the tokens ​

• The same value gets the same token within one session: one agent token on one server process. Two records that mention the same email show the same token, so the agent can see they match.
• Counters are shared, so a token's number says nothing about the record. Do not parse it.
• They are not stable across sessions. A restart of the server, or a different agent token, starts a new table. A token an agent remembers from yesterday may not resolve today.
• They never leave the permission path. A token only resolves if the agent could read the record the value came from.

Passing tokens back ​

When the agent writes, it can use a token where the value would go. The server replaces it before saving:

curl -s -X POST http://127.0.0.1:8080/api/lead/create \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'content-type: application/json' \
  -d '{"title":"Support renewal","contact_name":"NAME_5","contact_email":"EMAIL_4"}'

A person opening that lead sees the real name and email. The agent only ever handled the tokens. A token the server cannot resolve is refused with 400 {"error":"invalid token"}.

If the agent types a real value instead (for example because a user told it), the value is saved as given and shown to the agent as a new token afterwards.

Filtering by a masked field ​

An agent cannot filter or sort on a masked or withheld field. The request fails as if the field did not exist: unknown field party.email. This is on purpose: otherwise an agent could find a hidden value by guessing and checking.

What to put in the agent's instructions ​

Personal data is masked. You will see placeholders such as NAME_1 or EMAIL_2. Never try to guess or reconstruct the real value. To use a person's details in a new record, copy the placeholder. If a field is listed as withheld, tell me you cannot see it instead of asking for it.

What masking does not do ​

• It does not read free text. If a person types a customer's phone number into a note, that note is shown as it is unless the field is marked as personal data.
• It protects fields, not reasoning. An agent that is told a real value in chat can repeat it. Keep real personal data out of prompts.
• It is not a legal guarantee. Treat it as one layer; see Security and privacy.

Background: Data classes and masking.