> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bluprynt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts theme={"system"}
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](#scopes). |
| `accessToken` | `string` | Yes | A token from your server's [token endpoint](/sdk/tokens). Mint a fresh one each time you call `kyi()`. |
| `options` | `KYIOptions` | No | Lifecycle callbacks. See [Callbacks](#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

```ts theme={"system"}
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](/sdk/flow).

### Callbacks

```ts theme={"system"}
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`

```ts theme={"system"}
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. |

<Warning>Don't restyle these classes beyond z-index fixes. They aren't a versioned API and can change between releases.</Warning>

## `generateToken()`

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

```ts theme={"system"}
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:

```json Header theme={"system"}
{ "alg": "HS256" }
```

```json Payload theme={"system"}
{
  "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](/sdk/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](/sdk/errors).

## TypeScript types

```ts theme={"system"}
import type { KYIMode, KYIScope, KYIOptions, KYIWidget } from '@bluprynt/kyi-widget-sdk'
import type { GenerateTokenOptions } from '@bluprynt/kyi-widget-sdk/server'
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.