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
- List your origins. In Vaults → your vault → Secure components, add each website (
https://app.yourbank.example) and each app (rvapp://com.yourbank.wallet). - A service account for minting. Give it an access rule allowing
tokenizeon the fields you collect, anddetokenize(with the decision you want people to see) on the fields you reveal. - 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
Node.js
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
Web
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
| Symptom | Cause | Fix |
|---|---|---|
Frame is blank; console shows a frame-ancestors error | Page origin isn’t listed under Secure components | Add the exact origin, with scheme and port |
invalid_client_token straight away | Token minted for another origin, already used, or expired | Mint per page view; check origin matches |
invalid_client_token after a typo | Not this: format errors don’t spend the token | Check for a second submit() racing the first |
policy_denied on reveal | The rule has approved networks, and the browser isn’t on one | Rules are checked against the browser’s IP, not your server’s |
| Works on desktop, fails on mobile data | bindIp was set to an address that changed | Leave bindIp out for mobile networks, or mint just before use |
Next
Last updated on