vouch SDK

This is the vouch SDK, a TypeScript library for interacting with vouch. Currently, it allows you to generate links to start the web proof flow or direct users to a widget page.

Installation

To install the vouch SDK, you can use npm or other package managers.

npm install @getvouch/sdk
yarn add @getvouch/sdk
pnpm add @getvouch/sdk
bun add @getvouch/sdk

Usage

Create a vouch instance with your customerId and apiKey:

import { Vouch } from "@getvouch/sdk";
const vouch = new Vouch({
  customerId: "customer-id", // Your unique customer ID.
  apiKey: "your-api-key", // Your API key for authentication.
});

You may also provide additional configuration options:

import { Vouch } from "@getvouch/sdk";
const vouch = new Vouch({
  customerId: "customer-id",
  apiKey: "your-api-key",
  vouchHost: "https://app.getvouch.io", // The base URL for the Vouch API. Can be a string or an URL object. Defaults to "https://app.getvouch.io".
});

Get data source URL

Generate a link to start the vouch flow.

const { verificationUrl, requestId } = await vouch.getDataSourceUrl({
  datasourceId: "93826be6-6c7d-495a-9859-de5a1d17f30b", // Datasource ID. Here we use example.com data source. Must be a UUIDv4.
  redirectBackUrl: "https://docs.getvouch.io/getting-started/first-steps", // Return destination.
  webhookUrl: "https://docs.getvouch.io/api/web-proof", // (Optional) Proof delivery endpoint.
});

Adding inputs

Learn more about inputs.

Suppose, you want to use a datasource with the following inputs schema:

{
  name: string;
  minFollowersCount: number;
}

You'd then need to provide the inputs when generating the data source URL:

const { verificationUrl, requestId } = await vouch.getDataSourceUrl({
  /// ...similar to the previous example
  inputs: {
    name: "John Doe",
    minFollowersCount: 1337,
  },
});

The inputs will be encoded to base64, so you'd see something like this inside the URL: inputs=eyJuYW1lIjoiSm9obiBEb2UiLCJtaW5Gb2xsb3dlcnNDb3VudCI6MTMzN30

Get start URL (deprecated)

Deprecated: Use getDataSourceUrl instead. getStartUrl constructs the URL client-side and requires you to manage requestId manually. getDataSourceUrl creates the proof request on the server and returns both the URL and requestId.

Get widget URL

Generate a link to a widget page where users can choose from available data sources. Requires customerId and apiKey in the constructor.

const { verificationUrl, requestId } = await vouch.getWidgetUrl({
  widgetId: "41b9a0c3-1234-4678-9abc-def012345678", // Your widget ID. Must be a UUIDv4.
  redirectBackUrl: "https://example.com/callback", // Return destination after proof completion.
  webhookUrl: "https://example.com/webhook", // (Optional) Proof delivery endpoint.
});