wellknown.id docs
Contents

API reference

Web SDK (web.js)

The web SDK as a page sees it: <script src="https://wellknown.id/sdk/web.js"> defines the <wellknown-id-button> element, tells the page how each sign-in ended with two window events, and adds window.WellknownId. Types only: the script is served by wellknown.id, not installed.

Interfaces

WellknownIdApi

window.WellknownId, once the script has run.

Methods

linkKey()
linkKey(): Promise<LoginResult>;

Links another wellknown.id to the account the page is signed in to (prd.md §4.9): a second sign-in in a popup, in which the holder picks the other one. Call it from a click. Resolves the other sign-in's result, whose sub your site links to the current account; nothing changes at wellknown.id. Also emitted as wellknown-id-link-success.

Returns

Promise<LoginResult>

WellknownIdEvents

The events the script dispatches on window, and their detail.

Properties

PropertyType
wellknown-id-link-successCustomEvent<LoginResult>
wellknown-id-login-failureCustomEvent<LoginFailure>
wellknown-id-login-successCustomEvent<LoginResult>

Type Aliases

LoginFailure

type LoginFailure = object;

The detail of wellknown-id-login-failure: how it was trying, and why it ended (a message starting try_again asks for another click).

Properties

PropertyType
errorstring
mode?string | null

LoginResult

type LoginResult = object;

How a sign-in ended well: the detail of wellknown-id-login-success, and what linkKey() resolves.

Properties

PropertyTypeDescription
access_token?stringAn opaque access token, valid 60 seconds, for nothing but itself: wellknown.id has no userinfo.
claimsRecord<string, unknown>The verified ID token's claims (or the self-issued token's).
id_token?stringThe ID token, verified against wellknown.id's keys, for your backend to verify again.
mode?stringHow it went: fedcm, popup, popin or navigate.
self_issued?stringThe self-issued token, where the site took it itself, and the verifier its nonce was made from (for its backend).
substringThe holder's did:key at your site: the account.
verifier?string-

ScriptParams

type ScriptParams = object;

What the script's URL takes, as query parameters: clientId (your domain; this page's hostname by default), mode (default, fedcm, popup, popin, navigate), redirectUri (this page by default), backend (your endpoint that redeems codes, on this origin), selfIssued (1: take self-issued tokens yourself, where your config allows them), and target (the id of an element to put the button in). The element takes mode and client-id as attributes, over the script's.

Properties

PropertyType
backend?string
clientId?string
mode?"default" | "fedcm" | "popup" | "popin" | "navigate"
redirectUri?string
selfIssued?"1" | "true"
target?string