Skip to Content
Onshore is in early access. Don’t load real customer data until the items in Known limits are closed.
DevelopersTask guidesCollect and reveal in the front end

Collect and reveal in the front end

Secure components keep values out of your front end and your servers altogether. A form or a revealed value sits in a component the vault controls; your code handles only tokens.

Browser / app Your server Vault │ 1. "I want to add my ID" │ │ │ ─────────────────────────▶ │ 2. createClientToken ──────▶ │ │ ◀──── client token ─────── │ ◀──────── rvct_… ──────────── │ │ 3. mount the form with the token, person types │ │ ──────────────────── value goes straight to the vault ───▶ │ │ ◀─────────────────────────── tokens ────────────────────── │ │ 4. send tokens ─────────▶ │ 5. save tokens │

One-time setup

  1. List your origins. In Vaults → your vault → Secure components, add each website (https://app.yourbank.example) and each app (rvapp://com.yourbank.wallet).
  2. A service account for minting. Give it an access rule allowing tokenize on the fields you collect, and detokenize (with the decision you want people to see) on the fields you reveal.
  3. Content Security Policy on your web pages: script-src https://vault.yourbank.example; frame-src https://vault.yourbank.example.

Collect an ID number

Server: an endpoint that mints a collect token

app.post("/api/secure/collect-id", requireUser, async (req, res) => { const { client_token, expires_at } = await vault.createClientToken(VAULT, { kind: "collect", origin: req.get("x-app-origin") === "ios" ? "rvapp://com.yourbank.wallet" : "https://app.yourbank.example", fields: ["national_id"], subjectRef: req.user.customerId, // ties the stored value to this customer bindIp: req.ip, // only this address can use the token ttlSeconds: 300, }); res.json({ clientToken: client_token, expiresAt: expires_at }); });

Client: show the form

const { clientToken } = await api.post("/api/secure/collect-id"); const form = Onshore.collect({ vault: "v_live_gb01", clientToken, labels: { national_id: "NI number" } }).mount("#ni"); saveButton.onclick = async () => { const { national_id } = await form.submit(); await api.post("/api/profile/national-id", { token: national_id }); };

Server: save the token

app.post("/api/profile/national-id", requireUser, async (req, res) => { const token = String(req.body.token); if (!/^tok_uk_nino_[A-Za-z0-9]{8,}$/.test(token)) return res.sendStatus(400); // only accept a token await db.customers.update(req.user.customerId, { national_id_token: token }); res.sendStatus(204); });

Check the shape: the endpoint should only ever accept a token, so a buggy or hostile client can’t send a raw value instead.

Reveal to a support agent

Server: check access, then mint

app.post("/api/secure/reveal/:customerId", requireAgent, async (req, res) => { const customer = await db.customers.get(req.params.customerId); const ticket = await helpdesk.ticket(req.body.ticketId); // Your rules: this agent is assigned to an open ticket for this customer. if (ticket.customerId !== customer.id || ticket.assignee !== req.agent.id || ticket.closed) { return res.sendStatus(403); } const { client_token } = await vault.createClientToken(VAULT, { kind: "reveal", origin: "https://support.yourbank.example", tokens: [customer.national_id_token, customer.iban_token], purpose: `Ticket ${ticket.id}`, onBehalfOf: req.agent.email, bindIp: req.ip, ttlSeconds: 60, }); res.json({ clientToken: client_token }); });

This check is the important part. Access rules apply to the minting service account, which can usually reveal for any customer. Only your server knows whether this agent should see this customer.

Client: show the values

const { clientToken } = await api.post(`/api/secure/reveal/${customerId}`, { ticketId }); Onshore.reveal({ vault: "v_live_gb01", clientToken, labels: { 0: "NI number", 1: "IBAN" }, hideAfter: 60 }) .on("hidden", function () { this.unmount?.(); }) .mount("#customer-ids");

The values appear inside the frame only, and hide after 60 seconds. The audit log records the purpose, the agent (onBehalfOf), the browser’s IP and the decision for each value.

Common problems

SymptomCauseFix
Frame is blank; console shows a frame-ancestors errorPage origin isn’t listed under Secure componentsAdd the exact origin, with scheme and port
invalid_client_token straight awayToken minted for another origin, already used, or expiredMint per page view; check origin matches
invalid_client_token after a typoNot this: format errors don’t spend the tokenCheck for a second submit() racing the first
policy_denied on revealThe rule has approved networks, and the browser isn’t on oneRules are checked against the browser’s IP, not your server’s
Works on desktop, fails on mobile databindIp was set to an address that changedLeave bindIp out for mobile networks, or mint just before use

Next

Last updated on