POST /v2/auth/face/process

Creates or continues a FaceTec enrollment or match scan. Each scan consists of several request-response steps. At each step, the Device SDK produces a requestBlob. The app sends that blob to this endpoint, then passes the returned responseBlob back to the SDK. Repeat this exchange until completed is true.

The app sets purpose to select the operation. Use enroll to register the user's face for the first time, or match to compare a new live capture with the enrolled face. The first request returns a face_session_id, which must be included in every later request for the same scan. When a match completes with succeeded: true, that session can be used once to authorize device registration, keyshare recovery, or the combined register-and-recover operation.

Used in flow: Face enrollment before backup; face matching before keyshare recovery or new-device registration

Authentication: JWT (Access Token) with write:face for enroll or read:face for match

Request

Authorization: Bearer <access_token>
Content-Type: application/json

First request of a scan

{
  "purpose": "match",
  "requestBlob": "<blob from the Device SDK>",
  "userAgent": "<user agent string from the Device SDK>"
}

Every later request of the same scan

{
  "purpose": "match",
  "requestBlob": "<blob from the Device SDK>",
  "userAgent": "<user agent string from the Device SDK>",
  "face_session_id": "uuid_of_this_scan"
}

Field	Type	Required	Description
purpose	string	Yes	enroll for first-time registration, match for re-verification
requestBlob	string	Yes	Session request blob produced by the FaceTec Device SDK
userAgent	string	Yes	User agent string produced by the FaceTec Device SDK
face_session_id	string	Conditional	Omit on the first request of a scan. Required on every later request, using the value returned by the first one.

Response

Every response contains the same fields. Continue the request-response exchange until completed is true, and only then use succeeded to determine whether the scan passed.

200 OK

{
  "face_session_id": "uuid_of_this_scan",
  "purpose": "match",
  "responseBlob": "<blob to pass back into the Device SDK>",
  "completed": false,
  "succeeded": false
}

Session rules

• The purpose is checked against the user's enrollment state before anything is sent to FaceTec. enroll is rejected once a face is registered, and match is rejected until one is.
• For each user, starting a new scan retires any pending scan with the same purpose, so at most one scan per purpose is active.
• A session expires FACETEC_SESSION_EXPIRY_SECONDS after it starts. A successful match gets a fresh window of the same length from the moment it completes, so a slow scan does not eat into the time the app has to spend it.
• A successful match session can be spent exactly once. Device registration, keyshare recovery, or the combined register-and-recover operation consumes it.
• auth-svc resolves and stores the FaceTec external database reference for the user. It is never part of the request or response.

Errors

400 Bad Request - a required field is missing

{
  "error": {
    "code": 100227,
    "message": "Missing FaceTec requestBlob"
  }
}

Missing purpose returns code 100225, a purpose other than enroll or match returns 100226, and a missing userAgent returns 100228.

409 Conflict - enroll when a face is already registered

{
  "error": {
    "code": 100604,
    "message": "Face already registered for this user"
  }
}

404 Not Found - match before a face is registered

{
  "error": {
    "code": 100309,
    "message": "Face not registered for this user"
  }
}

409 Conflict - continuing a scan that already finished or expired

{
  "error": {
    "code": 100606,
    "message": "FaceTec session is no longer active"
  }
}