--- name: bt-pii description: Vault and govern PII and documents. license: MIT metadata: tier: standard last_verified: '2026-09-25' --- # PII and non-card sensitive data ## The model: store once, shape on the way out Fact: tokens carry the encrypted data; **expressions** shape what comes out — masks for safe display, aliases for format-preserving substitutes, detokenization for full values, search indexes and fingerprints computed at creation (https://developers.basistheory.com/docs/expressions/, masks: https://developers.basistheory.com/docs/expressions/masks, aliasing: https://developers.basistheory.com/docs/expressions/aliasing, fingerprints: https://developers.basistheory.com/docs/expressions/fingerprints, filters: https://developers.basistheory.com/docs/expressions/filters, configuration: https://developers.basistheory.com/docs/expressions/configuration). Design decisions that must happen at _token creation_ (they cannot be retrofitted onto existing tokens): search indexes (https://developers.basistheory.com/docs/expressions/search-indexes), fingerprints for dedupe, mask shape, and container placement (https://developers.basistheory.com/docs/concepts/what-are-containers). Get these into the schema conversation on day one. ## Capabilities and canonical docs - **Search encrypted data**: https://developers.basistheory.com/docs/concepts/what-is-search, API: https://developers.basistheory.com/docs/api/tokens/search, guide: https://developers.basistheory.com/docs/guides/process/search-data. Search works on indexed fields — the index decision above. - **Reveal/detokenize**: https://developers.basistheory.com/docs/api/tokens/detokenize, https://developers.basistheory.com/docs/expressions/detokenization; display flows: https://developers.basistheory.com/docs/guides/share/reveal-tokenized-data, masked display: https://developers.basistheory.com/docs/guides/share/display-masked-data, from third parties: https://developers.basistheory.com/docs/guides/share/reveal-data-from-third-party. - **Documents** (files as vaulted objects — KYC docs, statements): https://developers.basistheory.com/docs/api/documents/api. Fact (verified 2026-09-25): one file per request, and the 15 MB limit applies to the whole multipart body including the `request` field and boundaries, so the largest file that fits is slightly under 15 MB; over-limit requests return `400` `Request body too large`. Chunk or compress on the customer side, not by splitting a document across requests. - **Govern and audit**: control access https://developers.basistheory.com/docs/guides/govern/audit-data-access and https://developers.basistheory.com/docs/guides/govern/control-data-access; access-rule guidance in `bt-architecture`. - **Analytics on encrypted data**: https://developers.basistheory.com/docs/guides/process/analyze-data. - **Global/regional data**: https://developers.basistheory.com/docs/features/global-data. Residency and regulatory _interpretation_ is a validation area: state what the feature does, route compliance conclusions to the customer's counsel and Basis Theory. - Blueprint worth copying for API-shaped PII products: https://developers.basistheory.com/docs/blueprints/personal-information/query-user-data-from-api (index: https://developers.basistheory.com/docs/blueprints/personal-information/). ## Existing-code mode 1. Inventory what is being stored and — more important — every path it currently _exits_ the system (UI display, exports, support tools, logs). The exit paths decide masks, aliases, and access rules; storage is the easy half. 2. Define token types/schemas with masks, indexes, and fingerprints up front. Prefer masks-by-default in every read path; full detokenization only where the workflow genuinely requires the raw value, behind narrow application scopes. 3. Replace direct DB reads of sensitive columns with token references; keep the customer's data model, swapping column contents for token IDs. 4. Audit: log token access with correlation to the acting user (govern guides above); make "who saw what, when" answerable before launch — retrofitting audit is far more expensive than including it. 5. Tests: masked read path, authorized full reveal, unauthorized reveal rejected (the test that matters), search by indexed field, dedupe via fingerprint. ## POC scaffold mode Per `bt-start/references/poc-conventions.md`: a small service that creates PII tokens (person: name, SSN, email) with masks + search indexes + fingerprints, exposes masked list / authorized reveal / search-by-SSN endpoints, and a seed automation with obviously fake data. Zero real PII anywhere, test tenant only, and a final report labeling retention policy, legal basis, and residency choices as Custom (customer-owned). For a POC, scaffold in the directory the user selected, include `.env.example` with placeholder variables, and close with done / assumed / remaining / proof run / production items. ## Basis Theory implementation guidance When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it. - `../_shared/references/implementation-guidance/pii-and-sensitive-data/` - `../_shared/references/implementation-guidance/documents-and-pii/` - `../_shared/references/implementation-guidance/sessions/` ## Working conventions (shared by all Basis Theory skills) - Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs. - Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness. - Never request, echo, store, or commit real credentials. Use placeholders such as `` and prefer sandbox or synthetic data for examples. - If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing. - Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval. - Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change. - Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations. - End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.