> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/sdks/web-sdk.md).

# Web SDK

Start the VOVE ID verification journey from a web application.

The Web SDK opens the VOVE ID verification journey and returns the client-side outcome through a callback.

## Install

```bash
npm install @vove-id/web-sdk
```

Or:

```bash
yarn add @vove-id/web-sdk
```

Create the session token on your backend. Never put the private `x-api-key` in browser code.

## Start a verification

```typescript
import { Vove, VoveEnvironment } from '@vove-id/web-sdk';

const vove = new Vove();

vove.start({
  sessionToken: tokenFromYourBackend,
  publicKey: 'public_sandbox_replace_me',
  environment: VoveEnvironment.Sandbox,
  showUI: true,
  onVerificationComplete(status) {
    handleVerificationStatus(status);
  },
});
```

Use `VoveEnvironment.Sandbox` with Sandbox credentials and `VoveEnvironment.Production` with Production credentials.

The callback drives the browser experience. Confirm the current server-side result after a verified webhook before making a final decision.

## Configuration

```typescript
type VoveStatus = 'success' | 'pending' | 'canceled' | 'failed';

interface VoveConfig {
  sessionToken: string;
  publicKey: string;
  environment: VoveEnvironment;
  onVerificationComplete?: (status: VoveStatus) => void;
  showUI?: boolean;
}
```

| Field                    | Required | Description                                                                  |
| ------------------------ | -------- | ---------------------------------------------------------------------------- |
| `sessionToken`           | Yes      | Short-lived token created by your backend.                                   |
| `publicKey`              | Yes      | Public SDK key from the same environment as the token.                       |
| `environment`            | Yes      | `VoveEnvironment.Sandbox` or `VoveEnvironment.Production`.                   |
| `onVerificationComplete` | No       | Receives the verification outcome.                                           |
| `showUI`                 | No       | Shows or hides the built-in welcome and summary screens. Defaults to `true`. |

The type sketch documents the fields used by `start`; use the declarations shipped with your installed package as the compile-time authority.

## Handle every callback status

```typescript
function handleVerificationStatus(status: VoveStatus) {
  switch (status) {
    case 'success':
      showAwaitingServerConfirmation();
      break;
    case 'pending':
      showPendingReview();
      break;
    case 'canceled':
      showVerificationCanceled();
      break;
    case 'failed':
      showVerificationFailed();
      break;
  }
}
```

## Hosted-link alternative

You can also open the hosted verification journey directly. Build the URL with `URLSearchParams` so values such as the redirect URL are encoded correctly.

```typescript
const params = new URLSearchParams({
  authToken: tokenFromYourBackend,
  publicKey: 'public_sandbox_replace_me',
  environment: 'Sandbox',
  lg: 'en',
  enableVocalGuidance: 'false',
  showUI: 'true',
  redirectURL: 'https://app.example.com/verification-callback',
});

window.location.assign('https://web.voveid.net/?' + params.toString());
```

The redirect can contain a `status` query parameter. Treat it as client input and confirm the result on your backend.

## Troubleshooting

| Symptom                               | Check                                                                   |
| ------------------------------------- | ----------------------------------------------------------------------- |
| The journey does not start            | Confirm the public key, session token, and environment match.           |
| The token is rejected                 | Request a fresh token from your backend; do not reuse an expired token. |
| The callback does not run             | Check browser errors and confirm the journey reached an outcome.        |
| The hosted redirect is malformed      | Construct the URL with `URLSearchParams`.                               |
| Sandbox works but Production does not | Confirm Production access and the approved domain configuration.        |

See [session creation](/docs/kyc-api/verification-session.md), [webhooks](/docs/kyc-api/webhooks.md), and [production readiness](/docs/production-readiness.md).