PII Vault

The PII Vault is an encrypted store for sensitive user records with consent-gated retrieval, GDPR-style deletion, and a queryable audit trail. It complements the redaction proxy: the proxy keeps PII out of LLM prompts, while the vault gives you a compliant place to keep the PII you do need to store.

Every record is encrypted with AES-256-GCM envelope encryption (KMS-backed) before it is written. Plaintext is never stored, and read endpoints return either metadata or the encrypted envelope — decryption happens in your approved environment.

Authentication & scopes

Vault endpoints authenticate with a Treza API key plus an account header:

Authorization: Bearer treza_live_...
x-treza-account: <your account identifier>

The x-treza-account value must match the account that owns the API key (the identifier shown in the dashboard — your sign-in email or wallet address). Each endpoint requires a specific scope on the key:

Scope	Grants
pii:ingest	Store new records (pii:write is an alias)
pii:read	List record metadata, retrieve envelopes
pii:delete	Delete records
pii:consent	Grant, revoke, and list consents
pii:audit	Query the access audit log

Create keys with only the scopes each service needs.

Ingest a record

POST /api/pii/ingest — requires pii:ingest

curl -X POST https://trezalabs.com/api/pii/ingest \
  -H "Authorization: Bearer $TREZA_API_KEY" \
  -H "x-treza-account: $TREZA_ACCOUNT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "passport",
    "payload": { "number": "X1234567", "country": "US" },
    "consentGiven": true,
    "metadata": { "source": "onboarding" }
  }'

Field	Type	Notes
type	string	Required. Your data-type label (e.g. passport, email)
payload	string/object	Required. Encrypted before storage; objects are JSON-serialized
consentGiven	boolean	Optional consent flag recorded on the row
processorEnclaveId	string	Optional. Pins the record to one of your PII_PROCESSOR enclaves
metadata	object	Optional non-sensitive metadata

{
  "piiId": "pii_1718039482_x9y8z7w6v",
  "processorEnclaveId": null,
  "encryption": "AES_256_GCM_KMS_ENVELOPE"
}

Every ingest is recorded in the audit log.

List records

GET /api/pii/list?account=<your account identifier> — requires pii:read

curl "https://trezalabs.com/api/pii/list?account=$TREZA_ACCOUNT" \
  -H "Authorization: Bearer $TREZA_API_KEY" \
  -H "x-treza-account: $TREZA_ACCOUNT"

Returns metadata only — never ciphertext or plaintext:

{
  "records": [
    {
      "piiId": "pii_1718039482_x9y8z7w6v",
      "dataType": "passport",
      "status": "active",
      "createdAt": "2026-06-10T12:00:00.000Z",
      "processorEnclaveId": null
    }
  ]
}

Retrieve a record (consent-gated)

POST /api/pii/retrieve — requires pii:read

Retrieval only succeeds when an active consent exists for the record's data type and the stated purpose. Denied attempts are recorded in the audit log as violations.

curl -X POST https://trezalabs.com/api/pii/retrieve \
  -H "Authorization: Bearer $TREZA_API_KEY" \
  -H "x-treza-account: $TREZA_ACCOUNT" \
  -H "Content-Type: application/json" \
  -d '{
    "piiId": "pii_1718039482_x9y8z7w6v",
    "purpose": "kyc-verification"
  }'

{
  "piiId": "pii_1718039482_x9y8z7w6v",
  "dataType": "passport",
  "purpose": "kyc-verification",
  "envelope": { "algorithm": "AES_256_GCM_KMS_ENVELOPE", "...": "..." },
  "processorEnclaveId": null,
  "note": "Decrypt envelope inside an approved TEE using KMS."
}

The response contains the encrypted envelope, not plaintext — decrypt it inside your approved processing environment.

Optionally pass processorEnclaveId (and an attestationDocument) to require attestation verification of a PII_PROCESSOR enclave before the envelope is released; verification failure returns 403.

Error	Meaning
403 No active consent for this data type and purpose	Grant consent first (logged as a violation)
403 Attestation verification failed	Enclave attestation check did not pass
404 PII record not found	Unknown, deleted, or not-active record

Consent management

GET /api/pii/consent?account=<id> — list consents (requires pii:consent) POST /api/pii/consent — grant or revoke (requires pii:consent)

Grant consent for a data type and recipient/purpose:

curl -X POST https://trezalabs.com/api/pii/consent \
  -H "Authorization: Bearer $TREZA_API_KEY" \
  -H "x-treza-account: $TREZA_ACCOUNT" \
  -H "Content-Type: application/json" \
  -d '{ "dataType": "passport", "recipient": "kyc-verification" }'

{ "consentId": "consent_1718039482_q1w2e3r4t", "dataType": "passport", "recipient": "kyc-verification", "active": true }

The recipient is matched against the purpose supplied at retrieval time. Use any (or *) as a wildcard recipient to allow all purposes for that data type.

Revoke a consent:

curl -X POST https://trezalabs.com/api/pii/consent \
  -H "Authorization: Bearer $TREZA_API_KEY" \
  -H "x-treza-account: $TREZA_ACCOUNT" \
  -H "Content-Type: application/json" \
  -d '{ "revoke": true, "consentId": "consent_1718039482_q1w2e3r4t" }'

Grants and revocations are both written to the audit log. Consents expire automatically after three years.

Delete a record (right to erasure)

POST /api/pii/delete — requires pii:delete

curl -X POST https://trezalabs.com/api/pii/delete \
  -H "Authorization: Bearer $TREZA_API_KEY" \
  -H "x-treza-account: $TREZA_ACCOUNT" \
  -H "Content-Type: application/json" \
  -d '{ "piiId": "pii_1718039482_x9y8z7w6v" }'

{ "piiId": "pii_1718039482_x9y8z7w6v", "status": "pending_delete", "ttl": 1750705269 }

Deletion is designed for GDPR/CCPA erasure requests:

1. The ciphertext is removed immediately — the record is unrecoverable from this moment.

2. The row is marked pending_delete and the residual metadata is purged automatically within 30 days.

3. The deletion is written to the audit log.

Deleting a non-active record returns 409; a record you don't own returns 404.

Audit log

GET /api/pii/audit — requires pii:audit when querying by account

Every vault operation (ingest, retrieve, delete, consent grant/revoke) and PII-access events flushed from Treza SDK workflows are queryable:

curl "https://trezalabs.com/api/pii/audit?account=$TREZA_ACCOUNT&violations=true&limit=50" \
  -H "Authorization: Bearer $TREZA_API_KEY" \
  -H "x-treza-account: $TREZA_ACCOUNT"

Query param	Description
account	Your account identifier (required unless workflowId is given)
workflowId	Filter to one SDK workflow
workflowRunId	Filter to one workflow run
violations	true to return only events flagged as violations
startDate	ISO date lower bound
limit	Max events (default 100, cap 500)

{
  "summary": { "total": 2, "violations": 1, "workflows": ["wf_onboarding"] },
  "events": [ { "eventId": "pii_...", "hadViolation": true, "timestamp": "..." } ]
}

Audit events are retained for 90 days.

The PII Vault audit log (/api/pii/audit) tracks access to stored records. The redaction proxy has its own log (GET /api/redact/log) tracking entities redacted from LLM traffic — see the Quickstart.