Docs · For users

Concepts

The core building blocks of VirtualID and how they fit together: one identity, many profiles, controlled exposure, revocable sharing, live subscriptions, and private contacts.

Identity

Each account has one master identity, addressed by the username you chose at signup. Your identity owns your fields and your profiles. There is exactly one identity per account in the MVP.

Fields

A field is one piece of information about you — a name, email, phone, company, medical detail, or government ID. Fields come from two places:

A seeded field catalogue of standardized field types, each with a key, display metadata, and per-country validation rules (e.g. GET /field-types/{key}/validation?country=US).
A small number of custom fields you define yourself.

Each field instance carries a sensitivity. High-sensitivity fields (medical, government IDs, insurer/policy) get stronger, client-side / zero-knowledge protection at rest.

Profiles

A profile is a purpose-scoped presentation of your identity — Work, Public, Medical, and so on. Profiles are how you show different people different subsets of yourself from a single source of truth. Change a field once and every profile that exposes it updates.

Exposure (the visibility matrix)

Exposure is the mapping of which fields a profile reveals. It is default-deny: a profile shows nothing until you explicitly expose a field on it. The exposure matrix is set with PUT /profiles/{id}/exposures and changing it is a step-up action (fresh authentication required), because it changes what plaintext a profile can reveal.

Why step-up matters. Because of the two-key model, the server alone can never widen a profile's exposure — only you, with your account key, can. See Security & privacy.

Sharing

You share a profile via a share link and its QR code, or an invitation code. Links have a kind (e.g. QR link), an expiry, an approval mode (auto or explicit), and a max-uses limit. Permanent links back business cards, RFID tags, and public profiles. Every link can be revoked immediately.

Subscriptions

When someone redeems your link, they create a subscription to that profile. Two sides:

Owner side — you approve, deny, move (to a different profile), or revoke subscriptions.
Subscriber side — the profiles you subscribe to are your contacts.

Updates use an event-then-pull model: a lightweight "changed" event (SSE/WebSocket, carrying no data) tells subscribers something changed; their client then pulls the new values (POST /my/contacts/{id}/pull). Revocation removes access immediately.

Contacts, notes & labels

My Contacts is your subscriber-side view. On each contact you can keep multiple timestamped notes and labels — private annotations encrypted to you. The counterparty and the server operator cannot read them. Search across contacts runs client-side (notes are decrypted and indexed locally, so there are no per-keystroke server calls).

Public profiles

You can publish a public profile at virtualid.one/id/<alias> (path form in the MVP). Public-tier fields are, by definition, not encrypted and clearly labelled as outside the confidentiality guarantee. Anyone can view a public profile and export it as a vCard.

Deferred (post-MVP): OAuth logins, the developer / OAuth-app platform, CardDAV auto-refresh, phone auto-sync, custom domains/subdomains, the Business tier + DPA + business invitation flow, consent-preferences, and AI skills/MCP. These are designed but not part of the MVP slice.