Skip to Content
Onshore is in early access. Don’t load real customer data until the items in Known limits are closed.
DevelopersTask guidesReveal values safely

Reveal values safely

Revealing turns tokens back into values, as access rules allow. Done well, a value appears only where a person needs it, for a reason that’s recorded, and leaves no copy behind.

How a reveal is decided

For each token, the vault finds the access rules that apply to the caller (its role, the field, the network it’s calling from, the time) and returns the most permissive decision they allow:

Decisionvalue holdsTypical rule
plaintextThe full valueA payments service that must send the account number to a bank
maskedThe field’s mask, such as •• •• •• 56 C or ****6789Support agents confirming identity
token_onlyThe token itselfServices that only need to pass it on
deniednothingAnyone without a rule

On top of the rules:

  • Restricted people reveal as denied, whatever the rules say.
  • Reveal limits on a rule (for example 200 plaintext reveals per hour per agent) return 429 rate_limited once used up.
  • Approved networks on a rule apply to the caller’s IP: a rule that only allows the office network won’t apply from home.
  • Break-glass: someone without a rule can ask for temporary access, which a second person approves. It’s logged prominently.

Always give a real purpose

The purpose is recorded next to every value revealed, and it’s what an auditor or regulator reads. Make it specific enough to answer “why was this seen?”:

WeakStrong
"support""Ticket 88213, agent ada@yourbank.example"
"batch""Statement run 2026-11, job 4471"
"view customer""KYC review case 551"

Don’t put customer values in a purpose. If one slips in, the vault removes recognised identifiers before logging it: Ticket 7 for AB123456C is recorded as Ticket 7 for [uk_nino removed].

Handle every decision

type Shown = { kind: "full" | "masked"; text: string } | { kind: "hidden" }; function toShown(r: DetokenizeResult): Shown { switch (r.decision) { case "plaintext": return { kind: "full", text: r.value! }; case "masked": return { kind: "masked", text: r.value! }; default: return { kind: "hidden" }; // token_only and denied: show nothing useful } } const results = await vault.detokenize(VAULT, [c.national_id_token, c.iban_token], `Ticket ${ticket.id}`); const [nationalId, iban] = results.map(toShown);

Never fall back. If a reveal throws, show nothing and say the value is unavailable. Don’t show the token, a cached value, or a value from another system. That’s what “fail closed” means, and the SDKs are built around it.

Ask for less

A rule might allow plaintext, but a page that only confirms identity doesn’t need it. Ask for masked; the decision can only narrow:

const [r] = await vault.detokenize(VAULT, [{ token: c.national_id_token, redaction: "masked" }], "Account overview");

Use this on list views, dashboards and anywhere a full value isn’t the point. It shrinks what a compromised session or a shoulder-surfer could see.

Reveal in the browser, not through your server

If a person needs to see a full value on screen, a reveal component shows it inside a frame from the vault: your servers, your API responses and your front-end code never hold it. Reveal through your server only when your server needs the value itself (to send to a bank, to print a statement).

Don’t let revealed values leak

LeakPrevention
Logged in an API responseDon’t return plaintext from your API; use a reveal component. If you must, exclude the field from response logging
Error trackers capture variablesScrub fields named like value, or wrap revealed values in an object whose toString() hides them
Cached by your serverDon’t cache plaintext. Re-reveal when needed; the vault is fast (single-digit milliseconds at p95 for a batch of 10)
Cached by the browserCache-Control: no-store on any response containing a value
Kept in analytics or a warehouseSend tokens, never values
Seen in a screenshotMobile reveal views hide after a time and when the app goes to the background; Android blocks screenshots

Batch reveals

A statement job revealing 50,000 addresses: pass them all to one detokenize call (the SDK sends 500 at a time), use continueOnError so one erased customer doesn’t stop the run, and give a purpose naming the job.

const results = await vault.detokenize(VAULT, addressTokens, `Statement run ${month}, job ${jobId}`, { continueOnError: true }); const missing = results.filter((r) => r.error?.code === "token_not_found").length; const notAllowed = results.filter((r) => r.decision && r.decision !== "plaintext").length; if (notAllowed) throw new Error(`job's access rule doesn't allow plaintext for ${notAllowed} addresses`);

Batch jobs need a service account with a rule allowing plaintext for those fields, ideally limited to the job’s network and hours.

Reading a whole record

If you stored with insertRecord, read everything back with one call:

const fields = await vault.getRecord(VAULT, customer.onshore_record, `KYC review ${caseId}`); for (const [name, r] of Object.entries(fields)) render(name, toShown(r));

Next

Last updated on