Persona PII, Key, Session, and Webhook Controls
Overview
Treat the integration as a high-sensitivity identity boundary. Separate server API keys, short-lived inquiry session tokens, and webhook secrets; minimize collected PII; authenticate every event; and make destructive redaction an explicit governed operation.
Prerequisites
- Data-flow and threat model for the Persona integration
- Owners for credentials, privacy, incidents, retention, and redaction
- Approved environment, template, webhook, and access-control inventory
Instructions
Step 1: Classify secrets and data
Inventory bearer keys, webhook secrets, session tokens, identity attributes, documents, images, logs, and derived decisions with owners and retention.
Step 2: Enforce environment isolation
Use distinct secret scopes, endpoints, templates, and access policies for sandbox and production. Deny production data in developer fixtures.
Step 3: Minimize privilege and exposure
Restrict keys and operator roles, keep Persona calls server-side, redact headers and bodies, and prevent session tokens from analytics or URLs.
Step 4: Authenticate raw events
Parse Persona-Signature, compute SHA-256 HMAC over timestamp + '.' + rawBody, compare all v1 candidates in constant time, and enforce a reviewed timestamp tolerance.
Step 5: Make processing replay-safe
Deduplicate event IDs and order business transitions by provider created-at, because deliveries may repeat or arrive out of order.
Step 6: Govern redaction
Require subject, resource, authorization, impact preview, child-resource expectations, and evidence before invoking redaction. It cannot be undone and child redaction is asynchronous.
Authentication
REST uses an environment bearer API key; event intake uses the endpoint webhook secret; browser flows receive only the intended inquiry session token. These credentials are not interchangeable.
Tool Discipline
Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.
Output
- Credential and sensitive-data inventory
- Webhook authenticity and replay-control design
- Retention, redaction, rotation, incident, and rollback controls
Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.
Examples
During secret rotation the endpoint accepts both current signing candidates, verifies every candidate against the raw body in constant time, records only the matching-secret generation, and removes the retired secret after the overlap window.
Error Handling
| Failure | Response |
|---|---|
| Signature valid only after JSON serialization | Reject it: verification must use the exact raw bytes received. |
| Secret or token in telemetry | Revoke or rotate as appropriate, contain access, and follow the incident plan. |
| Redaction target ambiguous | Stop; resolve the exact inquiry and child-resource impact before any destructive call. |
Validation
Verify the result against the linked first-party evidence, the pinned API version, redacted contract fixtures, an expected failure path, and the documented rollback or manual-disposition path. A successful request is not proof of a successful identity decision.