Skip to main content

​
CDP PII tokenization and vault

Six tabs on Integrations → CDP hold the tenant-owned controls for handling personal data in the CDP: PII tokenization, PII vault, Trait governance, Event property governance, Data catalog, and Erasure propagation. Together they cover one workflow — decide which identifiers get tokenized, run the tokenize/detokenize operations, classify what each trait and event property may be used for, audit the result in the catalog, and carry an erasure decision into every downstream destination. None of these surfaces mandates a compliance posture. Each one documents a control your organization configures: what to tokenize, who may classify, which uses you allow. The console exposes the same operations as the public API, so every section below shows both where the knob lives in the dashboard and the endpoint that drives it. All endpoints are rooted at https://api.orbit.devotel.io/api/v1/cdp. Reads and tokenize calls need owner, admin, or developer with the contacts:read scope; policy writes need contacts:write; every detokenize call narrows the role to owner or admin because it returns cleartext PII.

​
1. What PII tokenization governs

Tokenization replaces a sensitive identifier — an email, a phone number, a national identifier — with an opaque token before the value travels anywhere downstream. Segments, activations, and exports then run on tokens instead of cleartext, so a breached export or a leaked destination carries pseudonyms, not identities. Orbit exposes two families of token:
  • Deterministic reversible — the same cleartext value always maps to the same token inside your tenant (casing and whitespace variants of an email collide to one token), and a privileged caller can reverse the token back to cleartext. Use this when a downstream system occasionally needs the raw identifier back — a legal request, a fulfillment handoff.
  • Hash — an irreversible keyed pseudonym. The value is still deterministic (the same person’s records join on one token), but nothing can reverse it. Use this when joining and segmentation are all you need and you never want cleartext recoverable.
The PII tokenization tab renders the effective policy for each identifier type — email, phone, ssn, generic — with its override registry and a roll-up of how many types are enabled, and how many of those are reversible versus hashed. A type with no override resolves to disabled, so tokenization is opt-in per type.

​
Policy API

The GET response carries four blocks: policy (the resolved mode per type, with source telling you whether it came from an override or the default), the overrides registry, a catalog describing each type’s canonicalization (for example, email is lower-cased and trimmed so casing variants collide), and a summary with enabled_types, reversible_types, and hashed_types counts. A DELETE on a type with no override returns 404 — deletes are intentional, not idempotent resets.

​
Tokenize and detokenize

Tokenize never echoes the cleartext back — items that canonicalize to empty return a per-item error code instead of failing the batch. Detokenize is the privileged read: it is owner/admin only, every call is written to your tenant’s audit trail recording how many tokens were opened and which identifier types were revealed (never the values), and it is rate-limited to 60 calls per minute per tenant against 120 for tokenize. Within one tenant the tokenization keys are derived per organization, so a token from one tenant is unusable — and undecodable — in another.

​
2. PII vault — sealed envelopes and operator-open semantics

The PII vault tab is the sealed-envelope companion to policy-driven tokenization. Where /pii-tokenization applies your per-type policy, the vault is an explicit operator flow: you decide at call time whether a token must be openable later.
Three properties define the vault semantics:
  • The opaque token alone is never reversible. The deterministic lookup token is a keyed pseudonym; only the sealed (enc:v1:) envelope — issued when you request reversible: true — can be opened back to cleartext. Store the envelope if you will need detokenize later; by default the response carries tokens only and the cleartext is unrecoverable from it.
  • Opening is operator-gated. Detokenize narrows to owner/admin, and each call is audited with counts only — the audit entry records how many envelopes were requested and how many opened, never an identifier, token, or envelope.
  • Skipped, never partial. A value that is not a valid identifier of its declared type (for example a malformed national id) lands in the skipped list with its request index and your ref correlation key — the batch succeeds and bad input is reported, not hashed into a meaningless token.
Use the policy surface when tokenizing should be your standing posture; use the vault when one workflow needs a reversible handoff while everything else stays irreversible.

​
3. Trait governance — classify contact traits

The Trait governance tab classifies each contact trait by sensitivity, data categories, consent gating, and export masking. A trait with no entry resolves to public, so the registry is an opt-in overlay on your trait list. The sensitivity scale is ordered — most liberal to strictest: public, internal, pii, regulatory (GDPR special-category, HIPAA PHI, government IDs, financial accounts). Categories are a closed set of tags a data protection officer can filter by — email, phone, name, address, geo, dob, government_id, financial, health, biometric, demographic, behavioral, device, ip, other. Masking is a read-time projection for compliance exports (none through full redaction); it never rewrites the stored value.
The access view answers “which traits may a given role view or export?” — call it without role to answer for your own role, or pass a role to preview another’s access without impersonating it.

​
Advisory classification by name

You do not have to hand-write every entry. The classify endpoint inspects a trait’s name — never its values — and suggests a classification based on naming patterns:
Each suggestion returns the proposed sensitivity, categories, consent_required, and masking, plus the naming pattern that matched — a suggestion is advisory until you PUT it into the registry. Up to 200 names per call.

​
4. Event-property governance — the data dictionary for events

Traits are the contact-side half of the dictionary. The Event property governance tab covers the other half: the properties carried on tracked events. Classification is keyed by event_name → property_name and reuses the same vocabulary as trait governance — one sensitivity scale, one category set, the same masking strategies — so a property and a trait classify on identical axes. Each entry carries sensitivity, categories, an accountable owner, allowed_use (the governance policy — analytics, personalization, activation, ml_training, billing, support, fraud_detection), an optional consent_required gate with a specific consent_channel, and masking. Only sensitivity is required; a minimal { "sensitivity": "pii" } is a valid write, and everything else defaults to the unconstrained posture.

​
5. Data catalog and erasure propagation

The Data catalog tab is the read-only rollup of the classification work: one row per declared tracking-plan event plus one row per property, each carrying the sensitivity (none, pii, phi, financial, sensitive), owner, allowed use, and policy reference attached to it. Unclassified entries surface with sensitivity: "none" and classified: false on purpose — the governance value is partly in seeing what has not been classified yet. Filter by sensitivity, owner, or classified-only; the summary counts classified versus total entries per class.
The data catalog and identity rules guide covers the catalog in depth, including how classification is authored inside the tracking plan itself. The Erasure propagation tab holds the per-destination delete-versus-suppress policy that carries a completed erasure into every connected destination — HubSpot, Salesforce, Braze, Iterable, Customer.io, Klaviyo, and the CRM/ESP connectors. The policy is a map: each destination resolves to Delete, Suppress, or its native default, and the PUT fully replaces the map — a destination you omit reverts to its default.
CDP erasure propagation is the full operator guide for that surface — fanning a DSAR deletion into every downstream store, reading the per-destination status trail, and re-running a stuck leg.

​
6. Wiring the classify heuristics without leaking raw values

Both classify endpoints are deliberately name-only. They match on how a field is named — email_hash, health_risk_score, card_last4 — and never see the values the field carries. That property matters for a lawful rollout:
  1. Export your trait names and event property names from the tracking plan or the data catalog — names only, no sampled values.
  2. POST them to /cdp/trait-governance/classify or /cdp/event-property-governance/classify in batches of up to 200.
  3. Review each suggestion — the response includes the naming pattern that matched, so a wrong match is auditable — and adjust before persisting.
  4. PUT the reviewed entries into the registry.
At no point does a raw identifier, an email, or a health value leave your tenant in this flow: the heuristic input is a name, and its output is a suggestion you ratify. If a field’s name does not match any pattern, the endpoint returns suggested: null for it — classify it by hand rather than forcing the heuristic.

​
7. End-to-end checklist

A complete posture pass touches each tab once:
  1. PII tokenization — enable the types you segment on (reversible where a downstream handoff needs cleartext, hash where it never should), then verify with GET that the summary counts match your intent.
  2. PII vault — run one reversible tokenize for the handoff workflow, store the sealed envelope, and confirm detokenize opens it under an owner/admin key.
  3. Trait governance — classify every personal trait; run /classify first to draft, review, then PUT.
  4. Event property governance — classify the properties on your tracking plan events the same way, with allowed_use set where a purpose must be constrained.
  5. Data catalog — filter classified_only=false and drive the unclassified remainder to zero.
  6. Erasure propagation — confirm every connected destination resolves to the delete-or-suppress mode your counsel’s posture requires.
Every control on this page is tenant-owned configuration. Orbit documents the knobs; the posture is yours to set with your counsel. Nothing here mandates a specific compliance stance, and the defaults — tokenization disabled, traits at public, destinations at native — leave existing tenants exactly as they were.

​
Triage