Two files and a script tag.

Step 1

Publish your public key at /.well-known/id

Create an Ed25519 key pair for your site and publish its public half, with the exact addresses wellknown.id may send users back to, at https://your.site/.well-known/id:

{
  "version": 1,
  "relying_parties": [{
    "public_key_jwk": { "kty": "OKP", "crv": "Ed25519", "x": "…" },
    "redirect_uris": ["https://your.site/"],
    "client_name": "Your Site"
  }]
}

Your client_id is the key’s RFC 7638 thumbprint (SHA-256, base64url). Publish only the public key: a config that contains private key material is rejected. The same config can also be published in DNS, CBOR-encoded in a _wellknown-id TXT record (wellknownid=cbor:…); if both exist, DNS wins.

Step 2

Add the button

<wellknown-id-button></wellknown-id-button>
<script src="https://wellknown.id/sdk/web.js?clientId=YOUR_CLIENT_ID" defer></script>

Load it as a classic script (not type="module") so it can read its parameters. It picks the best way to sign in: the browser’s own FedCM dialog where available, otherwise a pop-up, falling back to a full-page visit if pop-ups are blocked. By default users come back to the current page (origin and path), which must be one of your redirect_uris. Set redirectUri to choose another.

Step 3

Receive the result

window.addEventListener('wellknown-id-login-success', (e) => {
  const { sub, id_token } = e.detail;  // sub: the user's did:key
  fetch('/session', { method: 'POST', body: id_token });
});
window.addEventListener('wellknown-id-login-failure', (e) => console.warn(e.detail.error));

The SDK has already redeemed the code with PKCE and checked the token in the browser. Your server must verify it again before trusting it:

• signature: EdDSA, against the keys at https://wellknown.id/jwks
• iss is https://wellknown.id, aud is your client_id, and exp is in the future
• sub is the user’s did:key. Use it as their stable identifier.

Prefer your own stack?

It’s standard OpenID Connect

Discovery is at https://wellknown.id/.well-known/openid-configuration. Use the authorization code flow with PKCE (S256) as a public client, with scope=openid, a nonce, and a redirect_uri from your config. Only the code flow is supported.

Coming next

Say what you require, in karu

Sites will be able to add a policy to their config, written in karu, a small policy language people can read:

allow login if action == "login";
deny  stale if context.auth_age_seconds > 300;

wellknown.id is in development. Endpoints and formats may still change before launch.