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

askFor()
askFor(paths): Promise<ClaimsAnswer>;

Asks the signed-in holder what their persona says about them (prd.md §4.10): paths are OpenID Connect's standard claims ([['email'], ['name'], ['address', 'locality']]). Their wallet asks them, and answers as the persona they signed in with here, only with what you asked for, stated by them (not proven). Call it from a click; it needs a browser with the Digital Credentials API. unchecked is what was disclosed, to show; before relying on it, send response, nonce and query to your server and check them there with verifyPersonaClaims(response, query, origin, nonce, now, sub) (@wellknown-id/wallet), passing your server's time and the sub you signed them in as.

Parameters
ParameterType
pathsstring[][]
Returns

Promise<ClaimsAnswer>

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

ClaimsAnswer

type ClaimsAnswer = object;

What askFor resolves: what was disclosed (unchecked), and the answer, nonce and query for the site's server to check.

Properties

PropertyType
noncestring
queryobject
responseunknown
uncheckedRecord<string, unknown>

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