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

# Server integration

# Server-side Integration: Securely Proxy Your Liveness API Calls

Integrating the Liveness SDK requires access to protected API endpoints and sensitive credentials such as your `client_id` and `client_secret`. Exposing these credentials—or directly accessing Cynopsis Liveness APIs from the browser or mobile app—can lead to serious security risks.

Instead, we **highly recommend** implementing a *proxy server* as a backend component of your system to handle all interactions with the Liveness APIs, as well as securely generate and store access tokens.

***

## Why Use a Proxy Server?

* **Credential Protection:** Your OAuth2 secrets (`client_id` and `client_secret`) should never be exposed to frontend or mobile code, as this risks misuse by malicious actors.
* **Token Management:** The proxy backend is responsible for generating and refreshing the `access_token` using the /oauth/token endpoint. The frontend will only receive temporary tokens or use tokenized API calls via your backend.
* **Enhanced Security:** All sensitive API requests and responses (including session IDs and liveness results) are managed on the server side, reducing attack surface and mitigating credential leakage.
* **Auditing & Monitoring:** Keeping all API interactions on your backend allows you to monitor, log, and audit API usage more efficiently.

***

## Liveness APIs to Integrate via Proxy

Your backend proxy should securely connect to the following Liveness endpoints and expose controlled interfaces to your frontend as needed:

### 1. **Get Session Token**

`POST /service/liveness-v2/get_session_token`

* **Purpose:** Initiate a new liveness workflow by getting a one-time session token.
* **Backend responsibility:**
  * Receive an accessToken (generated from your backend using `/oauth/token`).
  * Pass required headers, including `X-Domain-Id` (your domain ID), and any other required metadata as specified in the API documentation.
  * Return the session token to your frontend client.

### 2. **Create Liveness Session**

`POST /service/liveness-v2/liveness_session`

* **Purpose:** Create a liveness session to start the verification process.
* **Backend responsibility:**
  * Use the access token and include the `X-Domain-Id` header.
  * Optionally, log or pre-validate incoming requests.
  * Return the created session details to the frontend.

### 3. **Get Liveness Result**

`GET /service/liveness-v2/liveness_result/{session_id}`

* **Purpose:** Query the final result/status of the liveness check by session ID.
* **Backend responsibility:**
  * Restrict this call to authenticated/authorized users.
  * Attach the accessToken and the `X-Domain-Id` header as required.
  * Forward the result to the frontend for UI display or further processing.

***

## Example Sequence Diagram

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Proxy Server
    participant Cynopsis API

    %% Step 1: Initiate Session
    Client->>Proxy Server: Initiate session (e.g., /initiate-session)
    Proxy Server->>Cynopsis API: POST /oauth/token (with client credentials)
    Cynopsis API-->>Proxy Server: access_token
    Proxy Server->>Cynopsis API: POST /service/liveness-v2/get_session_token (+ X-Domain-Id)
    Cynopsis API-->>Proxy Server: session_token
    Proxy Server-->>Client: session_token

    %% Step 2: Start Liveness
    Client->>Proxy Server: Start liveness (pass session_token/required params)
    Proxy Server->>Cynopsis API: POST /service/liveness-v2/liveness_session (+ X-Domain-Id)
    Cynopsis API-->>Proxy Server: session_id
    Proxy Server-->>Client: session_id

    %% Step 3: Retrieve Result
    Client->>Proxy Server: Get liveness result (session_id)
    Proxy Server->>Cynopsis API: GET /service/liveness-v2/liveness_result/{session_id} (+ X-Domain-Id)
    Cynopsis API-->>Proxy Server: result
    Proxy Server-->>Client: result
```

***

## Proxy Server Implementation Tips

* **Use HTTPS** to communicate between your frontend, backend, and the Cynopsis API endpoints.
* **Never expose** your OAuth2 client credentials in frontend code, environment, or mobile apps.
* **Implement authentication** on your proxy endpoints to ensure only authorized clients/users can initiate liveness sessions or retrieve results.
* **Cache or refresh tokens** as needed on your backend to optimize performance.

***

### Next steps

* Build simple REST endpoints (Node.js, Python, etc.) in your backend to wrap each of the 3 critical Liveness endpoints, ensuring you pass the `X-Domain-Id` header in each relevant request.
* Ensure your frontend calls only your backend's proxy endpoints for all liveness operations.

***

By following this architecture, you will keep your credentials secure, comply with security best practices, and maintain full control over your integration with Cynopsis Liveness APIs.