How it works — wellknown.id

01 · A key, not an account

Your identity is a secret only you can unlock.

The first time you use wellknown.id, your device makes a secret, a random seed. You can have several, called personas, for work and home, say: your passkey unlocks them all, a recovery code unlocks one, and kivi is another way in. wellknown.id keeps the seed only encrypted, under keys that come from your passkey or code, so what our servers hold can’t be read, by us or by anyone who breaks in. The seed is opened only on your device, by wellknown.id’s own pages: as with any website, you trust the code we serve, and our aim is servers that hold no data about anyone.

From the seed, your device makes a key for each site you use. Its public half is your identifier there, written as a did:key: a string like . Anyone can check a signature against it, and nobody had to issue it.

Lose a device, and your passkey, a recovery code or kivi gets you back in on another. Recovery through people you trust is on the roadmap.

02 · A proof for every sign-in

You prove you hold the key, afresh each time.

When a site asks you to sign in, wellknown.id gives a single-use challenge to its sign-in page, in your browser. The page picks the persona you use at that site, and signs a short proof with that persona’s key for the site: it names your did:key, the site, and the challenge, and it lasts two minutes. If you sign in with kivi on your phone instead, kivi signs the same proof and only the proof leaves the phone.

wellknown.id checks the proof in memory, along with the site’s file and any rules the site has set. Only then does it hand the site a standard OpenID Connect code, which the site exchanges for an ID token naming your key. Nothing about the sign-in is kept: the code is deleted when it’s used, or after a minute.

Because the site is named in what you sign, a proof made for one site is useless at another. Because the challenge is single-use, a proof can’t be replayed either. A site that chooses to, in its file, can take the proof straight from your browser and check it itself; then wellknown.id isn’t sent your key at all.

03 · Recognised where you choose

Sites say who they are, on their own domain.

There is no registration with wellknown.id. A site publishes a small file at /.well-known/id listing the addresses it may send you back to. Its identifier is its domain, the name you see and the name your key signs for. On every sign-in, wellknown.id fetches the file from that domain and checks that the request matches it exactly, so an impostor can’t borrow a real site’s name.

04 · In your browser

The browser’s own dialog where it has one.

Browsers are adding sign-in to their own interface through a standard called FedCM. Where it’s available, as in Chrome, the first step is the browser’s own, which a page can’t imitate, and a small wellknown.id window then shows who is signing in, for about a second, and proves your key. Elsewhere that window does the whole job, and if pop-ups are blocked the page itself visits wellknown.id and comes straight back.

05 · What everyone learns

As little as possible.

A site learns your did:key and that you proved you hold it just now. No name, no email, no password. Every site gets its own did:key, made just for it, so sites can’t compare notes about you by your key. Each site’s key is derived from your seed, so the same site knows you on every device where your passkey, a recovery code or kivi brings it. Two personas are two different accounts at a site, unless you choose to join them.

wellknown.id keeps nothing about you. It checks your proof in memory, hands the site its token, and forgets: no user database, no cookie noting which key you used where, nothing in its logs. Your record of where you signed in is yours, encrypted by your own device before it’s stored. A site may even take the proof straight from your browser, and then wellknown.id never sees your key at all. What we can see goes through it all, including what you trust us for.

06 · Built on open standards

Nothing proprietary to adopt.