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:
- Take a pre-recorded video of the victim reading any digits, for example
5 2 9 1 7 3 8. - 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.randomIntin Node,crypto/randin Go), neverMath.random. - Format: 8 distinct digits from
1–9, for example48719352.- 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 from1–9is 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 (
challengeDigitson the React and Angular face recorders,Biometry.setChallengein Flutter). - Send your stored copy as
phraseto/v2/livenessand/v2/voice-verify./v2/face-verifytakes no phrase: it runs face recognition only. Ignore any phrase the device sends back. In the v2 JSONrequestpart 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-videoendpoint 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());});import ( "context" "crypto/rand" "encoding/json" "errors" "math/big" "time"
"github.com/redis/go-redis/v9")
const challengeTTL = 5 * time.Minute
// generateChallenge returns 8 distinct digits from 1-9, shuffled with a CSPRNG.func generateChallenge() (string, error) { digits := []byte("123456789") for i := len(digits) - 1; i > 0; i-- { n, err := rand.Int(rand.Reader, big.NewInt(int64(i+1))) if err != nil { return "", err } j := n.Int64() digits[i], digits[j] = digits[j], digits[i] } return string(digits[:8]), nil}
// attemptID comes from your server-side session, never from the request.func challengeKey(attemptID string) string { return "liveness-challenge:" + attemptID }
// Issue: store it against the login attempt, return it for display.func issueChallenge(ctx context.Context, rdb *redis.Client, attemptID string) (string, error) { challenge, err := generateChallenge() if err != nil { return "", err } if err := rdb.Set(ctx, challengeKey(attemptID), challenge, challengeTTL).Err(); err != nil { return "", err } return challenge, nil}
// Verify: take the stored copy once, then build the liveness request with it.func livenessRequestJSON(ctx context.Context, rdb *redis.Client, attemptID, userID, sessionID string) ([]byte, error) { challenge, err := rdb.GetDel(ctx, challengeKey(attemptID)).Result() if err == redis.Nil { return nil, errors.New("challenge expired or already used") } if err != nil { return nil, err } return json.Marshal(map[string]string{ "user_id": userID, "session_id": sessionID, "phrase": challenge, // your stored copy, never one the device sent }) // Send this as the "request" form field, with the uploaded video as the // "video" file part, to POST /api-gateway/v2/liveness.}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.
<bio-face-recorder *ngIf="challenge" [challengeDigits]="challenge" (confirmRecording)="uploadVideoOnly($event.file)"></bio-face-recorder>See Angular components.
// challenge came from your backend, e.g. "48719352"Biometry.setChallenge(challenge);BiometryScannerWidget( phrase: biometry.phraseWords, onCapture: (video) => uploadVideoOnly(video),);See Flutter SDK.
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.