A share link gives a copy of an item, or some text, to anyone. The person who opens it needs no account, no
app and no sign-in. The content is encrypted on the sender’s device with a new key that only the link holds,
after the #, which browsers never send to a server. The account server keeps the ciphertext and counts
opens; it can’t read what was shared. See SPEC §22 for the format.
A link is a copy: editing or deleting the item later doesn’t change it. It ends when it expires, when it has been opened as many times as allowed, when its owner revokes it, after five wrong passcodes, when its owner loses access to the vault, or when the vault’s organisation turns share links off.
Making a link
import { DEFAULT_SHARE_FIELDS, findEntry, itemOf, itemSharePayload, shareableFields } from "@openvireo/sdk";
const item = itemOf(findEntry(vault.vault, { groupPath: [], entry: entryId }), { reveal: true });
// What can be shared, in display order: [{ name: "UserName", field: { k: "username", … } }, …]
const choices = shareableFields(item);
const payload = itemSharePayload(item, DEFAULT_SHARE_FIELDS, "Sam"); // username, password, website
const link = await account.createShare(payload, {
expiresIn: 7 * 86400, // seconds: 1 hour to 30 days (free plans: 7 days)
maxOpens: 1, // null or left out: until it expires
vaultId: vault.id,
entryId: item.id,
});
console.log(link.url); // https://share.openvireo.com/<id>#<key>
shareableFields lists an item’s username, password, website, notes, one-time code (name: "otp", whichever
way the TOTP is stored) and custom fields. Sharing the one-time code shares the TOTP secret, so the person who
opens the link can make codes until it expires; say so where people choose it.
For text that isn’t in a vault, use textSharePayload(text, title?) and leave out vaultId and entryId.
A passcode is a second secret, sent another way. The link alone, or the passcode alone, opens nothing:
import { textSharePayload } from "@openvireo/sdk";
const link = await account.createShare(textSharePayload("The alarm code is 4321", "Front door"), {
expiresIn: 3600,
passcode: "tiger lily 42",
});
createShare fails with plan_limit (details.limit is share_links or share_link_days) when the plan
doesn’t allow more, and forbidden when the vault’s organisation doesn’t allow links (item_share_links on
GET /me’s orgs is managers or off).
Listing and revoking
for (const s of await account.listShares()) {
// ref is { vault, entry, title }, readable only by this account
console.log(s.ref?.title, s.status, s.opens, s.maxOpens, s.expiresAt, s.endReason);
}
await account.revokeShare(id);
Links that ended in the last 30 days stay in the list with their endReason: expired, opened, revoked,
passcode, access_lost or policy.
Owners and admins choose who in an organisation may make links from its vaults:
await account.auth.setOrgShareLinks(orgId, "managers"); // "on" (default), "managers" or "off"
Turning links off, or limiting them to managers, ends the links that are no longer allowed.
Opening a link
The @openvireo/sdk/share entry point opens a link without an account, and loads no OPAQUE, KDBX or sync
code, so a public page stays small. It needs the account server’s API URL, which the page knows from its own
configuration:
import { getShareInfo, openShare, parseShareLink, parseTotpUri, totpCode } from "@openvireo/sdk/share";
const { id, key } = parseShareLink(location.href);
const info = await getShareInfo(api, id); // { expiresAt, opensLeft, kdf }; doesn't count as an open
// Show a "Reveal" button and open only when it's pressed: link previews then can't use up a one-time link.
const passcode = info.kdf ? await askForPasscode() : undefined;
const { payload, opensLeft } = await openShare(api, { id, key }, { passcode, info });
for (const f of payload.fields) {
const shown = f.k === "totp" ? totpCode(parseTotpUri(f.value)).code : f.value;
// render as plain text; hide f.protected values until shown
}
openShare fails with not_found for a link that ended or never existed (the two look the same),
passcode_required when a passcode is needed and none was given, and invalid_passcode with
details.attemptsLeft for a wrong one.
The SDK docs cover OpenVireo SDK, develop (54c2a02), last updated 21 November 2026. Found a mistake? Edit this page on GitHub.