Skip to Content
Onshore is in early access. Don’t load real customer data until the items in Known limits are closed.
DevelopersSecure components

Secure components (web)

Collect or show an ID number, account number or your own data type inside a frame on your site. Your page and servers get a token back and never see the value. Set up the allowed sites first: Secure components.

Collect

Mint a client token on your server

POST /v1/vaults/v_live_gb01/client-tokens { "kind": "collect", "origin": "https://app.yourbank.example", "fields": ["national_id"], "subject_ref": "cust_1042", "ttl_seconds": 120 }

Returns { "client_token": "rvct_…", "expires_at": "…" }. Single use; 2 minutes by default, 10 at most; tied to one origin and up to 10 fields.

Mount the form on your page

<script src="https://vault.yourbank.example/embed/rv.js"></script> <div id="national-id"></div> <button id="save" disabled>Save</button> <script> const form = Onshore.collect({ vault: "v_live_gb01", clientToken, // from your server labels: { national_id: "Your ID number" }, theme: { accent: "#2574de", radius: "8px" }, }); form.on("change", (e) => { save.disabled = !e.complete; }); form.mount("#national-id"); save.onclick = async () => { const tokens = await form.submit(); // { national_id: "tok_…" } // Send the token to your server. The value never came through this page. }; </script>

A format mistake shows inside the frame and doesn’t use up the token. submit() rejects with err.fields naming the fields to correct, never their contents.

Reveal

POST /v1/vaults/v_live_gb01/client-tokens { "kind": "reveal", "origin": "https://app.yourbank.example", "tokens": ["tok_…"], "purpose": "Support ticket 7", "on_behalf_of": "agent ada", "bind_ip": "203.0.113.7" }
Onshore.reveal({ vault, clientToken, labels: { 0: "ID number" }, hideAfter: 30 }).mount("#value");

The value shows inside the frame only, and hides after hideAfter seconds (30 by default, up to 300). Your page learns only the decision, such as masked or plaintext. A reveal token covers up to 20 tokens.

Your server must check that this person may see this record before minting a reveal token. Access rules apply to the service account that minted it, and the audit log records your purpose and on_behalf_of. Set bind_ip to the person’s address where you can.

Events

EventComponentCarries
readyCollect
changeCollectcomplete: every field is filled in
enterCollectThe person pressed Enter
invalidCollectfields to correct
completeCollecttokens
revealedRevealdecisions
hiddenReveal
errorBothcode

Styling

A short list of checked values: color, muted, background, inputBackground, border, accent, error, radius, fontSize and font (serif or mono). Free-form CSS isn’t allowed, because CSS could read what’s typed.

Security

  • The frame is a different origin; your page can’t read it.
  • Access rules are checked again when the token is used, against the browser’s address. An approved-network rule applies to the browser, not your server.
  • The frame allows only its own script and stylesheet, and only listed sites can frame it.
  • Card numbers can’t be collected here; they’re refused everywhere in the vault.
Last updated on