Skip to main content

​
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

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