Skip to content

Liveness challenge

In a liveness check the user reads a short sequence of digits aloud on camera. That sequence is the challenge. Biometry compares it with the phrase you send: on /v2/liveness, Visual Speech Recognition reads the digits from the user’s lips, and on /v2/voice-verify the voice engine checks the spoken digits as it matches the voice. So a video can only pass if it shows the person saying those digits.

That protects you only if the digits were unknown until moments before the recording. Your backend generates the challenge, keeps it, and sends its own stored copy to Biometry. The device only displays it.

Why the device’s phrase can’t be trusted

If the device picks the digits, or your backend forwards whatever phrase the device sends back, an attacker who controls the device (or calls your API directly) can do this:

  1. Take a pre-recorded video of the victim reading any digits, for example 5 2 9 1 7 3 8.
  2. Submit that video with the phrase "5291738".

The lip-reading and voice checks agree, because the phrase was chosen to fit the video. Face liveness and anti-video-forgery still run, but the challenge adds nothing.

When your backend chose the digits a minute ago and compares against its own copy, the attacker would need a video of the victim saying digits nobody knew in advance. The replay fails.

Rules

  • Generate it on your backend with a cryptographically secure random source (crypto.randomInt in Node, crypto/rand in Go), never Math.random.
  • Format: 8 distinct digits from 1–9, for example 48719352.
    • Why 8: the voice engine’s quality check needs at least 7 recognised words. With exactly 7 digits, one misheard digit already fails it; 8 leaves a margin. The Biometry console’s own login uses 8 digits too.
    • Why no 0: people say it as “zero”, “oh” or “nought”, and the voice engine works best when every digit has one pronunciation.
    • The capture components accept 7 to 12 digits, including 0, so other formats still display; 8 from 1–9 is what we recommend.
  • Record for about 10 seconds for 8 digits (recordingSeconds={10} on the capture components; the console uses the same). A clipped last digit fails the voice engine’s quality check.
  • Store it server-side, tied to this user’s login attempt (for example in Redis). Key it by an attempt or session ID that your server holds, from its own session state for the signed-in or signing-in user, never an ID the client sends in the request. Otherwise a client could ask for, or consume, another attempt’s challenge. Don’t round-trip the challenge through the client in a cookie, hidden field or token the client could change.
  • Rate-limit issuing. Limit how many challenges one user or login attempt can request (for example a few per minute), and let a new challenge replace the old one rather than add to it, so a client can’t keep asking until it gets digits it already has a recording of.
  • Expire it within 5 minutes (shorter is fine).
  • Use it once. Delete it as soon as the video arrives, whether the check then passes or fails. A retry gets a new challenge.
  • Give the device only the digits to display. Pass them to the capture component (challengeDigits on the React and Angular face recorders, Biometry.setChallenge in Flutter).
  • Send your stored copy as phrase to /v2/liveness and /v2/voice-verify. /v2/face-verify takes no phrase: it runs face recognition only. Ignore any phrase the device sends back. In the v2 JSON request part the digit string works as is: v2 spells digits out before comparing, so "48719352" and "four eight seven one nine three five two" are the same. The legacy v1 /process-video endpoint does not do this; send it the spelled-out words.

The flow

Device Your backend Biometry API
│ 1. start login │ │
│──────────────────────────────>│ 2. generate 48719352, store it │
│ 3. challenge "48719352" │ against this attempt (5 min) │
│<──────────────────────────────│ │
│ 4. user reads it on camera │ │
│ 5. upload video only │ │
│──────────────────────────────>│ 6. take and delete stored challenge │
│ │ 7. POST /v2/liveness │
│ │ phrase = stored copy │
│ │────────────────────────────────────>│
│ │<────────────────────────────────────│
│ 8. result │ │
│<──────────────────────────────│ │

Backend examples

Both examples keep the challenge in Redis with a 5-minute expiry and take it with GETDEL, which reads and deletes in one step, so the same challenge can’t be used twice even by two requests arriving together. Use whatever store you already have, as long as reading and deleting is atomic.

GETDEL needs Redis 6.2 or newer. On older Redis, do the read and delete in one transaction instead:

// Redis < 6.2: GET and DEL in one MULTI, so no other client runs in between.
const [challenge] = await redis.multi().get(key).del(key).exec();

req.loginAttempt in the examples stands for your server-side record of the login in progress (looked up from the user’s session), not anything read from the request body. Put your rate limit on the issue endpoint.

import { randomInt } from 'node:crypto';
const CHALLENGE_TTL_SECONDS = 5 * 60;
// 8 distinct digits from 1-9, shuffled with a CSPRNG.
function generateChallenge() {
const digits = ['1', '2', '3', '4', '5', '6', '7', '8', '9'];
for (let i = digits.length - 1; i > 0; i--) {
const j = randomInt(i + 1);
[digits[i], digits[j]] = [digits[j], digits[i]];
}
return digits.slice(0, 8).join('');
}
const challengeKey = (attemptId) => `liveness-challenge:${attemptId}`;
// Issue: called when the user starts the face check.
app.post('/api/login/challenge', async (req, res) => {
// Rate limit: at most 5 challenges per login attempt per minute.
const rateKey = `liveness-challenge-rate:${req.loginAttempt.id}`;
const issued = await redis.incr(rateKey);
if (issued === 1) await redis.expire(rateKey, 60);
if (issued > 5) return res.status(429).json({ error: 'too many challenges' });
const challenge = generateChallenge(); // replaces any earlier one below
await redis.set(challengeKey(req.loginAttempt.id), challenge, {
EX: CHALLENGE_TTL_SECONDS,
});
res.json({ challenge }); // the device displays this
});
// Verify: the device uploads only the video.
app.post('/api/login/liveness', upload.single('video'), async (req, res) => {
// Read and delete in one step: one use only.
const challenge = await redis.getDel(challengeKey(req.loginAttempt.id));
if (!challenge) {
return res.status(409).json({ error: 'challenge expired or already used' });
}
const form = new FormData();
form.append('request', JSON.stringify({
user_id: req.loginAttempt.userId,
session_id: req.loginAttempt.biometrySessionId,
phrase: challenge, // your stored copy, never req.body.phrase
}));
form.append('video', new Blob([req.file.buffer], { type: req.file.mimetype }), 'video.webm');
const response = await fetch(
'https://api.biometrysolutions.com/api-gateway/v2/liveness',
{
method: 'POST',
headers: { Authorization: `Bearer ${process.env.BIOMETRY_API_TOKEN}` },
body: form,
},
);
res.status(response.status).json(await response.json());
});

Showing the challenge on the device

// challenge came from POST /api/login/challenge, e.g. "48719352"
<FaceRecorder
challengeDigits={challenge}
onConfirmRecording={({ file }) => uploadVideoOnly(file)}
/>

See React components.

The components accept only digits, 7 to 12 of them, and show them exactly as given. An empty or invalid challenge raises an error instead of being swapped for other digits. When the challenge is omitted entirely (left out, null or never set), they still generate digits on the device, so existing apps keep working, but that fallback is deprecated, gives no replay protection, and logs a one-time deprecation warning (console.warn once per component instance in React and Angular, debugPrint once per process in Flutter) pointing here.