> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/general/integration-quick-start-guides/how-to-integrate-oz-liveness-into-your-web-application.md).

# How to Integrate Oz Liveness into Your Web Application

Oz Liveness Web SDK implements the ready-to-use face capture user interface that is essential for seamless customer experience and accurate liveness results. The SDK detects both presentation and injection attacks.

This guide walks you through your first liveness check using Web SDK and Oz API. Here, we cover the [SaaS model](/oz-knowledge/general/readme/saas-on-premise-on-device-what-to-choose.md#when-to-choose-saas).

The described flow combines:

* **Capture mode** – the Web SDK (or Mobile SDK) captures the Liveness video in the browser/app and the Client backend forwards it to Oz API. Capture results are not sent from the SDK straight to Oz API; the Client backend acts as an intermediary.
* **OzCapsula** – a proprietary encrypted binary container. The SDK packages the captured media into it; only Oz API can decrypt and process it. On the device it is an opaque blob – you cannot decode or inspect it, only forward it as-is.

Each step is marked:

* **\[Oz SDK]** – call our SDK API.
* **\[Your code]** – call your own backend or your own code.

`{{host}}` in the examples below is the base URL of your Oz API deployment, provided to you during deployment setup.

<figure><img src="/files/4oDCnSm3zZciyigLfhXV" alt=""><figcaption></figcaption></figure>

## Requirements

| Component | Minimum version |
| --------- | --------------- |
| Oz API    | **6.6.1**       |
| Web SDK   | **1.9.10**      |

You require a dedicated Web Adapter. Expand the section below if it has not yet been configured for your company.

<details>

<summary>How to obtain Web Adapter</summary>

Tell us domain names of the pages from which you are going to call Web SDK and email for admin access, e.g.:

| <p>Domain names from which Web SDK will be called:</p><ol><li>[www.yourbrand.com](http://www.yourbrand.com)</li><li>[www.yourbrand2.com](http://www.yourbrand2.com)</li></ol><p>Email for admin access:</p><ul><li><j.doe@yourcompany.com></li></ul> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

In response, you’ll get URLs and credentials for further integration and usage. When using SaaS API, you get them [from us](mailto:info@ozforensics.com):

| <p>Login: <j.doe@yourcompany.com></p><p>Password: …<br><br></p><p>API: https\://\<link>.com/</p><p>Web Console: https\://\<link>.com</p><p>Web Adapter: [https://web-sdk.\&#x3C;link>.com/your\_company\_name/](https://web-sdk.\&#x3C;link>.com/your_company_name/)</p> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

</details>

## Instructions

{% stepper %}
{% step %}

### (Oz SDK) Embed the plugin

Oz provides the plugin URL (served by the Oz-hosted adapter). Add it to your page:

```html
<script src="https://path-to-websdk/plugin_liveness.php"></script>
```

{% endstep %}

{% step %}

### (your code) Get a `session_token` from your backend

OzCapsula uses a session token. The token is mandatory for OzCapsula.

Your backend requests a session token from Oz API. Request it before each capture session, as close to the moment the user starts capture as possible.

**Endpoint:**

```
GET {{host}}/api/authorize/session_token
```

**Request:**

```shell
curl --location -g '{{host}}/api/authorize/session_token' \
--header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings
```

The authorization mechanism for calls to Oz API (`access_token`) depends on your installation settings: when using Instant API, you can integrate it under your own authorization scheme. If access token is required in your case, please check [Authentication](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/authentication). Never expose the access token in the browser. Also, please note that [access and session token are different tokens issued for different purposes](/oz-knowledge/other/faq.md#what-is-the-difference-between-access_token-and-session_token).

**Response:**

```json
{
  "session_token": "<session_token>"
}
```

This token is short-lived (default lifetime: 900 seconds). Request one per capture session and pass it to the SDK immediately – do not cache or reuse tokens across sessions.
{% endstep %}

{% step %}

### (Oz SDK) Launch the plugin with the `session_token`

```js
OzLiveness.open({
  lang: 'en',
  action: ['video_selfie_blank'],  // passive liveness
  session_token: session_token,    // session_token from Step 2
  on_capture_complete: function (action, ozCapsula) {
    // ozCapsula = the OzCapsula container (Blob) — Step 4
    sendToYourBackend(ozCapsula);
  },
  on_error: function (err) { /* handle */ }
});
```

{% endstep %}

{% step %}

### (Oz SDK) Get the OzCapsula container

When capture completes, the SDK fires the `on_capture_complete` callback. The container is delivered as the second argument – a `Blob` with MIME type `application/octet-stream`.

> The container is an **opaque encrypted blob**. You **cannot** decode it, inspect it, or extract individual images / frames / metadata from it on the device. It must be forwarded as-is to your backend. If you need access to captured images (e.g., [the best shot](/oz-knowledge/guides/developer-guide/api/oz-api/basic-scenarios/liveness/best-shot.md)), retrieve them from the Oz API analysis response on the server side.

Upload it to your backend as `application/octet-stream`.
{% endstep %}

{% step %}

### (your code) Send the container to Oz API

Your backend submits the container in a single synchronous `POST` request.

**Endpoint (Instant API):**

```shellscript
POST {{host}}/api/instant/folders/
```

**Endpoint (Full API):**

```shellscript
POST {{host}}/api/folders/
```

**Headers:**

* `Content-Type: application/octet-stream` (mandatory).
* `X-Forensic-Access-Token: {{access_token}}`. (optional, depends on installation settings).

**Request body:** the raw container bytes – no JSON envelope, no multipart, no base64 wrapping.

**Request (Instant API):**

```shell
curl -X POST '{{host}}/api/instant/folders/' \
  --header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'
```

**Request (Full API):**

```shell
curl -X POST '{{host}}/api/folders/' \
  --header 'X-Forensic-Access-Token: {{access_token}}' ## optional, depends on installation settings
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'
```

**On success:** HTTP `201` with a JSON folder object describing the result. Check Step 6.

**On container-level error:** HTTP `400` – see [Exceptions](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/ozcapsula-data-container#exceptions).

This guide covers the Liveness analysis. To perform a Face Matching analysis within the OzCapsula flow, see [How to Perform a Face Matching Analysis within OzCapsula Flow](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/ozcapsula-data-container/how-to-perform-a-face-matching-analysis-within-ozcapsula-flow).
{% endstep %}

{% step %}

### (your code) Handle the response

Your backend now has the response – a JSON folder object describing the result.

Make the accept/reject decision using only these two top-level fields:

```json
$.resolution_status   // "FINISHED" – analyses completed; "FAILED" – error during analysis processing
$.system_resolution   // "SUCCESS", "DECLINED", or "FAILED"
```

Interpret `system_resolution`:

* `SUCCESS` – all checks passed; accept the user.
* `DECLINED` – one or more checks failed; reject the user.
* `FAILED` – a system error prevented at least one analysis from completing; do not treat as accept or reject.

For per-analysis verdicts (for example, to know whether liveness passed but biometry failed), read `$.analyses[*].resolution_status` with the values described above.
{% endstep %}
{% endstepper %}

## Checklist

* [ ] Web SDK **1.9.10+**, Oz API **6.6.1+**.
* [ ] Step 1 embeds the plugin from the Oz-provided URL.
* [ ] Step 2 obtains a fresh `session_token` from your backend before every capture.
* [ ] Step 3 passes that `session_token` into `OzLiveness.open(...)`.
* [ ] Step 4 takes the container from the second argument of `on_capture_complete`; no attempt is made to decode/inspect it in the browser.
* [ ] Step 5 submits the container to `POST {{host}}/api/instant/folders/` (Instant API) or `POST {{host}}/api/folders/` (Full API) as raw bytes with `Content-Type: application/octet-stream`.
* [ ] The accept/reject decision uses only `resolution_status` and `system_resolution`.
* [ ] `session_token` is never cached, reused, or shared across sessions/users.

***

With these steps, you are done with basic integration of Web SDK into your web application. You will be able to access recorded media and analysis results in [Web Console](/oz-knowledge/guides/user-guide/oz-webui.md) via browser or programmatically via [API](/oz-knowledge/guides/developer-guide/api/oz-api.md) (please find the instructions here: [retrieving an MP4 video](/oz-knowledge/guides/developer-guide/sdk/oz-liveness-websdk/web-plugin/launching-the-plugin/capturing-video-and-description-of-the-on_capture_complete-callback.md#please-note), [getting analysis results](/oz-knowledge/guides/developer-guide/api/oz-api/basic-scenarios/liveness.md)).

In the [Web Plugin Developer Guide,](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/sdk/oz-liveness-websdk/configuration-and-usage/web-plugin) you can find instructions for common next steps:

* Customizing plugin look-and-feel
* Adding custom language pack
* Tuning plugin behavior
* Plugin parameters and callbacks
* Security recommendations

Please find a sample for Oz Liveness Web SDK [here](https://gitlab.com/oz-forensics/oz-liveness-sample-web/-/blob/master/OzLivenessWebSDKSample.html). To make it work, replace `<web-adapter-url>` with the Web Adapter URL you've received from us.

For Angular and React, replace `https://web-sdk.<link>.com` in index.html.

* [Angular sample](https://gitlab.com/oz-forensics/oz-liveness-sample-web-angular)
* [React sample](https://gitlab.com/oz-forensics/oz-liveness-sample-web-react/-/tree/main)
* [Vue](https://gitlab.com/oz-forensics/oz-liveness-sample-web-vue) sample
* [Svelte](https://gitlab.com/oz-forensics/oz-liveness-sample-web-svelte) sample


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge/general/integration-quick-start-guides/how-to-integrate-oz-liveness-into-your-web-application.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.