Template-Based PII Lookup

Template-based PII lookup lets a gateway key reference saved Eden Read templates and use the returned records as request-scoped redaction terms. This keeps PII masking additive to built-in detection, organization dictionaries, and key-level custom_pii_terms.

Use template lookup when the best source of truth for sensitive values is a system of record, such as a customer account table, account directory, CRM, ticketing system, or internal entitlement store.

Configuration Shape

Each lookup config defines:

Field	Purpose
`template_id` or `template_uuid`	Saved Eden `Read` template to execute.
`input_fields`	Values extracted from request JSON, user-message regex captures, headers, work metadata, or literals.
`records_path`	Optional JSON pointer to returned records. Empty means use the root response.
`redaction_fields`	JSON pointers inside each record mapped to a safe label and action.
`max_rows`	Maximum records to map into request-scoped terms.
`cache_ttl_secs`	Optional short-lived cache for lookup results.
`missing_input_mode`	Behavior when a configured input cannot be extracted.
`lookup_miss_mode`	Behavior when the template returns no matching record.
`error_mode`	Behavior when execution fails.

Example

json

{
  "pii_lookup_templates": [
    {
      "template_id": "lookup-customer-account-pii",
      "input_fields": [
        {
          "name": "account_id",
          "source": "user_message_regex",
          "pattern": "(?i)account(?: id)?[:# ]+(?P<value>[A-Z0-9-]+)",
          "required": true,
          "value_type": "string"
        }
      ],
      "records_path": "",
      "redaction_fields": [
        {
          "path": "/full_name",
          "label": "customer",
          "action": "redact"
        },
        {
          "path": "/email",
          "label": "email",
          "action": "redact"
        }
      ],
      "max_rows": 1,
      "error_mode": "block"
    }
  ]
}

Validation

Eden validates lookup configuration when a gateway key is created or updated, and validates again at runtime before execution:

The template exists in the organization.
The template kind is Read.
The gateway key owner has a valid agent identity for runtime checks.
The owner has read access to the template and endpoint.
Configured required inputs satisfy the template's required fields.
Regexes, JSON pointers, row limits, and output mappings are valid.

Runtime Flow

Eden parses the original client request JSON.
Configured input fields are extracted from JSON pointers, user-message regex captures, headers, work metadata, or literals.
Eden resolves and permission-checks the saved Read template under the gateway key owner's agent identity.
The template executes in sensitive mode.
Returned records are selected through records_path and mapped through redaction_fields.
Output values become request-scoped CustomPiiTerm entries.
Lookup-derived terms merge with built-in scanners, organization dictionaries, and key-level terms.
The existing PII policy runs once against the merged scanner before provider egress.

Failure Modes

Mode	Use
`missing_input_mode`	Decide whether missing extracted inputs skip, audit, or block lookup.
`lookup_miss_mode`	Decide what happens when the system of record returns no row.
`error_mode`	Decide what happens when template execution fails.

Runtime authorization failures, stale template configuration, non-Read templates, revoked access, and malformed persisted policy are configuration errors and fail closed.

Safety

Template execution uses sensitive mode for gateway lookups. Logs and telemetry include safe identifiers, status, cache state, row counts, and term counts, but never lookup input values, lookup output values, prompt text, or matched PII values.

Last updated: July 10, 2026