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
- Create a session with
POST /sessions. - Open the WebSocket with the session's
token(see WebSocket session). - Stream frames until the server sends
result. - Read the final outcome with
GET /sessions/{id}from your server.
Environments
| Environment | HTTP | WebSocket |
|---|---|---|
| Production | https://api.example.com/v1 | wss://api.example.com/ws |
| Sandbox | https://sandbox.example.com/v1 | wss://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
type | Fields | When |
|---|---|---|
frame | image (base64 JPEG, at most 640×480), ts (ms) | 5–10 frames per second |
action_done | action | When the player completed the requested move |
ping | Every 20 seconds, to keep the connection open |
Server to client
type | Fields | Meaning |
|---|---|---|
ready | expires_at | Start sending frames |
instruction | action: turn_left, turn_right, blink, smile | Show this move to the player |
progress | percent | Update the interface |
result | passed, score | The check is over |
error | code, message | Something went wrong; the socket closes next |
Example exchange
← {"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
| Code | Meaning |
|---|---|
1000 | The result was sent; the session is over |
4001 | The token is invalid or expired |
4008 | No frame for 30 seconds |
4029 | The 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
/sessionsoperationId: sessions_create
RequiresbearerAuth
Starts a liveness check and returns the WebSocket token for the player's device.
Request body
requiredYour own ID for the player.
Moves to ask for, in order. Random when omitted.
Responses
WebSocket token
Get a session
/sessions/{id}operationId: sessions_show
RequiresbearerAuth
Returns the session and, once the WebSocket sent result, its outcome.
Path parameters
Responses
WebSocket token
Rate limits
This section is marked x-traitTag: it shows its description without listing operations. Its operations still appear under Sessions.
| Scope | Limit |
|---|---|
| HTTP, per API key | 600 requests per minute |
| WebSocket, per session | 15 frames per second |
Above the limit, HTTP answers 429 with Retry-After; the WebSocket sends an error message and closes with 4029.
Models
Session
WebSocket token