Skip to Content
Onshore is in early access. Don’t load real customer data until the items in Known limits are closed.
Get startedHow it works

How it works

Onshore is built from a few ideas. Once you know them, every screen in the console makes sense.

The five ideas

1. A vault holds the real values, in one country

A vault is where real values are stored, encrypted, on servers in the country you chose when you created it. A vault’s country never changes. Each value is encrypted on its own with a data key, and data keys are themselves encrypted (“wrapped”) by a master key held in a separate key service or your own hardware security module (HSM). The database never holds a key it could use alone.

Each vault has fields: one per kind of value it keeps, such as national_id, iban or phone. A field decides what kind of token the value gets and how it’s shown when masked.

2. Tokens travel instead of values

When a value goes into the vault, you get back a token, such as tok_uk_nino_7Hq2xP9LmA4c. Your databases, logs, vendors and dashboards keep the token. A leaked token gives away nothing.

Token kindWhat it meansUse it for
Same value, same token (deterministic)The same value always gets the same tokenJoins, lookups, following one customer through your logs
New token each time (cell)Every store gets a fresh token, and its value can be changed laterRecords you edit, where linking isn’t wanted
Expires (transient)The token stops working after a set timeOne-time codes and short-lived values

And two formats:

FormatExampleUse it for
Clearly a token (opaque)tok_in_aadhaar_Qa81LmZ3Xe0dAlmost everything; nobody mistakes it for real data
Looks like the real value (format-preserving)9912 3456 7890Old systems that check a value’s length or shape

3. Detection finds values nobody labelled

Field rules protect fields you know about. But real exposure is the ID number inside an error message, or a customer typing their account number into a chat. Onshore’s detection engine reads free text and JSON and finds identifiers wherever they sit, using:

  • Country packs: the formats of each country’s IDs, accounts and phone numbers, with the issuer’s check digit where one is published. See Countries.
  • The Everywhere pack: names, emails, card numbers, amounts and international phone numbers, on for every vault.
  • Your own data types: patterns, keyword lists, values after a cue word, value lists and JSON fields. See Data types.

Each match gets a confidence score. Words nearby (“NI number”, “IBAN”) raise it; words like “invoice” can lower it.

4. Access rules decide who sees what

Nobody sees a real value unless a published access rule says so. When someone or something asks for a value, a rule looks at who is asking (their role), what (which field or data type), when (office hours, an approved network, multi-factor sign-in, a stated purpose) and returns one of four answers:

AnswerWhat the person gets
Real value (plaintext)The full value
MaskedPart of it, such as •• •• •• 56 C
Token onlyJust the token
DeniedNothing

With no rule, the answer is no. Where several rules match, the strictest wins. Publishing a rule can require a second person’s approval. See Access rules.

5. The audit log proves what happened

Every store, reveal, refusal, export, deletion and setting change writes an entry to an append-only, hash-chained audit log. Each entry includes the fingerprint of the one before it, so changing any entry breaks the chain. The log’s position is signed every day. Reports are computed from the log, never from separate counters. See Audit log.

How one value travels

It enters through a connection

A customer types their ID number into a secure form on your site, your server calls the SDK, a log line passes through the log processor, or a prompt passes through the AI gateway. These are all connections.

It’s found and stored

Detection (or a field rule) finds the value. The vault encrypts it in the country and returns a token.

The token goes on

The token, not the value, reaches your database, log vendor, model provider or helpdesk.

Someone asks for the real value

A support agent opens a record, or your backend detokenizes. An access rule decides: real, masked, token or no. If allowed, the value is decrypted in the country and shown.

It’s recorded

The request, the person, their stated reason and the answer go into the audit log. Reports and the residency map are built from these records.

The two halves of an install

HalfTouches real values?Contains
Data planeYes, and runs only in the vault’s countryVault API, detection and policy engines, log processor, AI gateway, HTTP proxy, file redactor, support tool adapters, PostgreSQL (values encrypted), the key service or your HSM
Control planeNoConsole, people and roles, access rules, connections, reports, webhooks

The control plane’s database role can’t read the vault’s data tables at all. Internal traffic between services uses mutual TLS. See Security model.

Every new connection and data type starts in watch only: Onshore counts what it would catch and changes nothing until you turn protection on.

Last updated on