KYI Widget SDK reference

Every function, option, callback, type and error in @bluprynt/kyi-widget-sdk.

The package has two entry points: a browser entry point that opens the widget, and a server entry point that signs access tokens. This page covers version 0.1.1. The types come straight from the SDK’s published typings.

Import	Runs in	Exports
@bluprynt/kyi-widget-sdk	Browser	kyi()
@bluprynt/kyi-widget-sdk/server	Node.js 18+	generateToken()

Both entry points ship as ESM and CommonJS, with TypeScript declarations.

kyi()

Opens the widget and returns a handle to it.

import { kyi } from '@bluprynt/kyi-widget-sdk'

function kyi(
  mode: 'drawer',
  scope: KYIScope,
  accessToken: string,
  options?: KYIOptions,
): KYIWidget

Parameter	Type	Required	Description
mode	'drawer'	Yes	How the widget is shown. drawer is the supported mode: a panel that slides in from the right.
scope	KYIScope	Yes	Which screen opens. See Scopes.
accessToken	string	Yes	A token from your server’s token endpoint. Mint a fresh one each time you call kyi().
options	KYIOptions	No	Lifecycle callbacks. See Callbacks.

Calling kyi() does the following:

1. It injects one <style id="bluprynt-kyi-styles"> element into <head>, once per page.
2. It appends a backdrop and a drawer (role="dialog", aria-modal="true") to <body>.
3. It loads https://app.bluprynt.com/widget/<scope>?token=<accessToken>&embed=true in an iframe inside the drawer.

Scopes

type KYIScope = 'kyi' | 'asset-list' | 'wallet-list'

Scope	Iframe path	Opens	Use it for
kyi	/widget/kyi	The verification flow. It starts KYB, or picks up where the member left off.	A “Verify your asset” or “Claim this profile” button.
asset-list	/widget/assets	The organization’s assets and their verification status.	An “Your verified assets” link in account settings.
wallet-list	/widget/wallets	The organization’s wallets: total, verified, pending and revoked.	A “Your verified wallets” link.

See every screen in Verification flow.

Callbacks

interface KYIOptions {
  onReady?: () => void
  onClose?: () => void
  onError?: (error: Error) => void
}

Callback	Fires when	Notes
onReady	The widget has loaded inside the iframe.	Use it to hide your own loading state.
onClose	The member closes the drawer with the close button, a backdrop click or Escape. It also fires when the widget closes itself.	Not called by destroy(). When the widget closes itself, version 0.1.1 can call onClose twice, so make your handler idempotent.
onError	The widget reports an error.	Receives an Error. Its message is the widget’s error text, or Unknown error if there is none.

The SDK only passes on messages that come from a bluprynt.com origin and from its own iframe. Messages from anything else are ignored.

KYIWidget

interface KYIWidget {
  destroy: () => void
  iframe: HTMLIFrameElement
}

Member	Description
destroy()	Removes the drawer, backdrop and listeners immediately, without the close animation. It does not call onClose. Call it when your page unmounts or your single-page app navigates away.
iframe	The widget’s <iframe>. Read it for testing or focus management. Don’t change its src.

Drawer behavior

Property	Value
Position	Fixed, full height, right edge.
Width	100% of the viewport, up to 760px. On phones it fills the screen.
Backdrop	Black at 50% opacity. Clicking it closes the drawer.
Close controls	Round close button at top right, Escape, backdrop click.
Animation	Slides in over 300 ms. On close, the elements are removed after the 300 ms animation.
Stacking	z-index: 999999 for the backdrop and 1000000 for the drawer.
Iframe permissions	allow="clipboard-write; web-share", so members can copy addresses and signing messages.
CSS classes	bluprynt-kyi-overlay, bluprynt-kyi-drawer, bluprynt-kyi-header, bluprynt-kyi-close, bluprynt-kyi-iframe, plus bluprynt-kyi-visible while the drawer is open.

Don’t restyle these classes beyond z-index fixes. They aren’t a versioned API and can change between releases.

generateToken()

Signs a short-lived access token for one of your members. Server only.

import { generateToken } from '@bluprynt/kyi-widget-sdk/server'

function generateToken(options: GenerateTokenOptions): Promise<string>

interface GenerateTokenOptions {
  issuer: string
  secretKey: string
  userId: string
  expiresIn?: number
}

Option	Type	Required	Becomes	Description
issuer	string	Yes	iss claim	Your partner ID, issued by Bluprynt.
secretKey	string	Yes	HMAC key	Your SECRET_KEY. Only ever read it from server-side configuration.
userId	string	Yes	sub claim	Your stable, unique, internal ID for the signed-in member.
expiresIn	number	No	exp claim	Lifetime in seconds. The default is 3600 (one hour).

The result is a compact JWT signed with HS256:

Header

{ "alg": "HS256" }

Payload

{
  "sub": "user-123",
  "iss": "your-partner-id",
  "iat": 1766146154,
  "exp": 1766149754
}

iat is the signing time and exp is iat + expiresIn, both in Unix seconds. The values above are an example. To sign tokens in another language, see Access tokens.

Errors

All errors are thrown synchronously from kyi(), or rejected from generateToken(), as plain Error objects.

Thrown by	error.message	Cause	Fix
kyi()	Access token is required	accessToken is empty or undefined.	Check that your token endpoint returned accessToken, and handle its error responses before calling kyi().
kyi()	Invalid mode: <mode>. Expected 'modal' or 'drawer'.	Unknown mode.	Pass 'drawer'.
kyi()	Invalid scope: <scope>	Unknown scope.	Pass kyi, asset-list or wallet-list.
generateToken()	Issuer is required	issuer is empty.	Set your partner ID in server config.
generateToken()	Secret key is required	secretKey is empty.	Set SECRET_KEY in server config. Fail closed with a 503.
generateToken()	User ID is required	userId is empty.	Only mint tokens for authenticated members. Return 401 otherwise.

Problems the SDK can’t detect, such as an origin that isn’t allowlisted, a wrong partner ID or an expired token, show up inside the drawer. See Errors and troubleshooting.

TypeScript types

import type { KYIMode, KYIScope, KYIOptions, KYIWidget } from '@bluprynt/kyi-widget-sdk'
import type { GenerateTokenOptions } from '@bluprynt/kyi-widget-sdk/server'

The source and typings also accept a 'modal' mode. Bluprynt’s official SDK docs cover only drawer, so treat modal as unsupported.