v1.2.0OpenAPI 3.0.3

Liveness API

Endpoints
2
Groups
1
Models
1

The Liveness API checks that a real person is in front of the camera. You create a session over HTTP, then the player's device streams camera frames over a WebSocket and receives the result live.

Getting started

  1. Create a session with POST /sessions.
  2. Open the WebSocket with the session's token (see WebSocket session).
  3. Stream frames until the server sends result.
  4. Read the final outcome with GET /sessions/{id} from your server.
Environments
EnvironmentHTTPWebSocket
Productionhttps://api.example.com/v1wss://api.example.com/ws
Sandboxhttps://sandbox.example.com/v1wss://sandbox.example.com/ws

Authentication

HTTP requests carry your API key in Authorization: Bearer …. The WebSocket uses the short-lived session token instead, so the key never reaches the player's device.

Errors

HTTP errors use the usual status codes with a JSON body { "error": "…" }. WebSocket errors arrive as an error message and then the server closes the socket (see Closing).

WebSocket session

The live connection between the player's device and the Liveness API. The messages below are UTF-8 JSON text frames.

Connecting

wss://api.example.com/ws?token={token}

The token comes from the POST /sessions response and is valid for 10 minutes. Once the socket opens, the server sends ready; do not send frames before that.

Messages

Every message is a JSON object with a type.

Client to server
typeFieldsWhen
frameimage (base64 JPEG, at most 640×480), ts (ms)5–10 frames per second
action_doneactionWhen the player completed the requested move
pingEvery 20 seconds, to keep the connection open
Server to client
typeFieldsMeaning
readyexpires_atStart sending frames
instructionaction: turn_left, turn_right, blink, smileShow this move to the player
progresspercentUpdate the interface
resultpassed, scoreThe check is over
errorcode, messageSomething went wrong; the socket closes next
Example exchange
json
← {"type":"ready","expires_at":"2026-10-14T10:10:00Z"}
→ {"type":"frame","image":"/9j/4AAQ…","ts":1760436000120}
← {"type":"instruction","action":"turn_left"}
→ {"type":"action_done","action":"turn_left"}
← {"type":"progress","percent":80}
← {"type":"result","passed":true,"score":0.97}

Closing

CodeMeaning
1000The result was sent; the session is over
4001The token is invalid or expired
4008No frame for 30 seconds
4029The session is open on another device

A dropped connection can be reopened with the same token before it expires; the session continues where it stopped.

Sessions

Records that start a liveness check and hold its result.

Create a session

post/sessions

operationId: sessions_create

RequiresbearerAuth

Starts a liveness check and returns the WebSocket token for the player's device.

Request body

required
referencestringrequired

Your own ID for the player.

Example: "player-48213"
actionsarray<string>

Moves to ask for, in order. Random when omitted.

Example: ["turn_left","blink"]

Responses

idstring
Example: "ses_8Hq2"
referencestring
Example: "player-48213"
statusstring
Values:"pending""connected""completed""expired"
Example: "completed"
tokenstring

WebSocket token

Example: "wst_3f9c1e7a2b"
ws_urlstring<uri>
Example: "wss://api.example.com/ws?token=wst_3f9c1e7a2b"
expires_atstring<date-time>
Example: "2026-10-14T10:10:00Z"
objectnullable

Get a session

get/sessions/{id}

operationId: sessions_show

RequiresbearerAuth

Returns the session and, once the WebSocket sent result, its outcome.

Path parameters

idstringrequired
Example: "ses_8Hq2"

Responses

idstring
Example: "ses_8Hq2"
referencestring
Example: "player-48213"
statusstring
Values:"pending""connected""completed""expired"
Example: "completed"
tokenstring

WebSocket token

Example: "wst_3f9c1e7a2b"
ws_urlstring<uri>
Example: "wss://api.example.com/ws?token=wst_3f9c1e7a2b"
expires_atstring<date-time>
Example: "2026-10-14T10:10:00Z"
objectnullable

Rate limits

This section is marked x-traitTag: it shows its description without listing operations. Its operations still appear under Sessions.

ScopeLimit
HTTP, per API key600 requests per minute
WebSocket, per session15 frames per second

Above the limit, HTTP answers 429 with Retry-After; the WebSocket sends an error message and closes with 4029.

Models

Session

idstring
Example: "ses_8Hq2"
referencestring
Example: "player-48213"
statusstring
Values:"pending""connected""completed""expired"
Example: "completed"
tokenstring

WebSocket token

Example: "wst_3f9c1e7a2b"
ws_urlstring<uri>
Example: "wss://api.example.com/ws?token=wst_3f9c1e7a2b"
expires_atstring<date-time>
Example: "2026-10-14T10:10:00Z"
objectnullable