Who decides when to ask for a new selfie?

You do. The trigger is a rule in your own system, such as a new device, a changed email address or an unusual login. Your backend starts the verification session when the rule fires.

What does the platform compare?

A returning user is compared with a stored reference face. The scenario settings include a required face match with a reference session. How a reference is set up for your flow is a conversation with the team. The liveness step asks the user to move the face closer through two ovals.

Is a successful session status enough to let the action through?

No. Read the liveness step as well: its status and the latest outcome.class say whether a live person was confirmed, and faceReference.reason says whether the required reference comparison matched. See the session object.

Account takeover re-authentication

The job

A password can be guessed, reused or stolen, and a one-time code can be read by someone who is not the owner. Once an attacker is inside an account, the first moves are usually the ones that keep the owner out and open a way to take value: change the email address, change the phone number, add a payout destination. A credential proves that someone holds a secret. It does not prove that the person who holds it is the person who signed up.

A fresh selfie with liveness asks a different question: is a live person here now? Where your flow adds a comparison with a stored reference face, it also asks whether this is the person you know. This page is about the moments when to ask and how to read the answer. For getting a locked-out user back in, see account recovery.

Where to ask

The platform does not see your logins. Your own system watches them, and starts a verification session when one of your rules fires. Three trigger points are common.

Trigger	Why it is a good moment to ask	What to hold
A new device or browser	The credential is correct, but nothing else about the visit is familiar.	The sensitive actions of the visit, or the whole visit, until the check is done.
Changed contact details	A new email address or phone number is the step that locks the owner out of every later warning.	The change itself, until the check passes.
An unusual login	Your own risk rules flagged the place, the time or the pattern.	The actions that move value or change access.

Do not ask on every login. A check that appears at every visit trains users to treat it as noise. Ask where an attacker gains the most, and let the rest of the account work as before.

The flow

The trigger. Your rule fires and holds the sensitive action. The rule is yours.
The session. Your backend issues a clientKey, an opaque identifier of your own and not an email address or a name, and encrypts it with the secret key of the scenario. Your page opens the widget with the scenario identifier and the encrypted key, and the widget creates the session. See working with clientKey.
The device. If the user is at a computer, a QR code moves the user to a phone. See QR hand-off.
The selfie and liveness. The user takes a selfie and moves the face closer through two ovals. See liveness.
The comparison. A returning user is compared with a stored reference face. The scenario settings include a required face match with a reference session. The set-up of the reference for your flow is agreed with the team, so talk to us before you rely on this step.
The lists. Repeat-user search and your own person lists and blocklists can be checked in the same flow, so that a face that belongs to another verified account or to a blocklist becomes a signal for review. See face search.
The result. Your backend reads the session status, or a webhook tells it that the session is complete.

The face API compares faces on its own, without a session. See the face API. Liveness is a step of a verification session, so a session is the route for this use case.

The decision

Decide on the server. The callbacks of the widget run in the browser of the user, and the user can tamper with them. Read the session your server fetches, then apply your policy.

One release rule applies to every path. The held action proceeds only when all of the following hold at the same time:

The session status is success, and the status of the liveness step is success.
The latest outcome.class of the liveness step is success. Only if your policy for this action allows it, a latest class of unverified on a step whose status is success is accepted instead.
The required reference comparison passed. Read it from faceReference.reason of the session: matched is the passing value, and mismatch is the failing verdict. Every other reason, and a missing faceReference block, means the faces were not compared, which is not a pass and does not mean a different person. Do not decide from a boolean alone.

Everything else is a hold or a refusal. A table row that does not meet all three conditions never lets the action through.

What your server reads	A reasonable policy
Session `success`, the liveness step `success`, latest `outcome.class` of `success`, and `faceReference.reason` of `matched`	Let the held action proceed.
The same, but the latest `outcome.class` is `unverified` (the attempt passed without the verifying services)	Let it proceed only if your policy for this action allows an unverified pass. Otherwise hold it and send the case to a person.
Session `success`, but `faceReference.reason` is `mismatch`	Keep the action held, and send the case to a person.
Session `success`, but `faceReference.reason` is any other value, or the block is missing	The faces were not compared. Keep the action held. Fix the reference set-up with the team, or offer another route.
`outcome.class` of `verdict`	The attempt was refused on a judgement about the person and is spent. Keep the action held, and send the case to a person.
`outcome.class` of `technical`	The machinery failed and the attempt is given back. Offer another attempt.
`outcome.class` of `exhausted`, or `triesLeft` of zero	The step is over. Keep the action held and offer another route.
`failed`	Keep the action held. Offer another attempt if your policy allows it, or send the case to a person.
`suspicious`	The platform flagged the result. Send it to a reviewer who can make a manual decision in the dashboard.
`expired`	The user did not finish in time. Treat it as no proof, and start a fresh session if the user asks again.
`exception`	Processing ended with an exception. Start a fresh session, or ask a reviewer to look at it.

On a liveness step, triesLeft shows the attempts still available, and zero means the step is over. See session statuses for the values.

A reviewer can change a session status by hand, so a status of success that a person set is not the same as a machine result. Release on the liveness step and the reference reason as read above, and record a manual decision as a decision of that person.

Keep the status the platform gave and the decision your system took in separate fields. A reviewer can change a status by hand later, and your record should show both what the platform said and what was done about it.

Scenario setup

Build the scenario in the scenario editor: the selfie step, the liveness step, and the options for repeat-user search and lists if you want them. A selfie and liveness scenario does not by itself compare the user with an earlier face. If you want that comparison, agree the reference set-up with the team first. The session lifetime is a setting of the scenario, from minutes up to a year, so a short lifetime suits a check that protects a single action. A session that nobody finishes reports expired.

What your system receives

A session status and a list of results for each step, including a liveness entry. Webhooks announce completion. See webhooks.

Talk to us about the trigger points of your product, or see the selfie and liveness screens on sample data in the interactive tour. For payments, see re-authentication before payments and withdrawals.