Injection Attack Detection (IAD)

This API, in the context of facial capture and evaluation, allows detection of:

Attack vectors: virtual cameras, external devices, browser attacks, network attacks.

Attack content: 3D rendering, facial morphing, face swap, cheap fake, deep fake.

This API requires client-side integration of the IAD capture libraries. The IAD capture library (included in Selphi) controls the capture process on the client and generates the IAD bundle (encrypted metadata and images package).

The API knows how to unpack the client's IAD bundle to perform both injection attack detection and presentation attack detection.

Endpoint

POST /iad

Headers

Name	Type	Required	Description
x-api-key	string	Yes	Access authorization API key.
OperationId	string	No	Operation identifier in Platform V2. If sent together with SessionId, a tracking event is issued in the Security tab of the operation details.
SessionId	string	No	Session identifier associated with the operation. Required to activate tracking, unless ExtraData.
ExtraData	string	No	Encrypted token that packages operationId and sessionId. Alternative to sending them separately.
Family	string	No	Tracking event family. By default ONBOARDING.

Request body

Content-Type: application/octet-stream

Parameters

Parameter	Type	Required	Description
IAD_BUNDLE	binary	Yes	Encrypted package of metadata and images. The bundle must be sent as a request application/octet-stream in the body.

Request example

curl --location '{IDENTITY_API_BASE_URL}/iad' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/octet-stream' \
--data 'IAD_BUNDLE'

Responses

200 Success

Response parameters

Parameter	Type	Description
attack	boolean	Boolean value indicating whether an attack was detected. true: an attack was detected, false: no attack was detected.

Response example

{
  "attack": true
}

400 Bad Request

When the request is invalid, the response includes a specific error code in the field errors that describes the problem detected. See IAD Error Codes.

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": [
    "FACE_ANGLE_TOO_LARGE: Facial out-of-plane rotation angle is extremely large"
  ]
}

IAD Error Codes

HTTP code	Message	Error code	Description
400	Face not found	FACE_NOT_FOUND	No faces were detected in the image.
400	Face is cropped	FACE_CROPPED	The face is only partially within the image.
400	Face is occluded	FACE_IS_OCCLUDED	The face is being partially hidden behind an object.
400	Too many faces detected	TOO_MANY_FACES	More than one face is visible in the image.
400	Facial out-of-plane rotation angle is extremely large	FACE_ANGLE_TOO_LARGE	The face angle relative to the camera viewpoint is too large.
400	Absolute face size is too small	FACE_TOO_SMALL	The face pixel density is very small; it should be closer to the camera or the image should have higher resolution.
400	Relative face size is too small	FACE_TOO_SMALL	The face is too small; it should be closer to the camera so that it occupies a larger portion of the image.
400	Face is too close to one or more borders	FACE_CLOSE_TO_BORDER	The face is too close to the edge of the camera view; it should be centered relative to the camera view.
400	Failed to parse file	UNKNOWN	The file is not a valid encrypted blob payload or is corrupted.
400	Failed to read metadata	UNKNOWN	The encrypted blob data was not generated in the correct format.
400	Failed to decrypt message	UNKNOWN	The public-private key pair configured on the server and in the capture library do not match.

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "Endpoint request timed out"
}

Integration with Platform V2 (optional)

If the operation is being tracked in Platform V2 / IDV Suite, the endpoint can emit a tracking event for each IAD call. This integration is optional and additive: not sending the tracking headers leaves the endpoint behavior identical to previous versions.

Activation

To activate tracking in a specific call, it is enough to include the headers OperationId and SessionId (or, alternatively, a ExtraData Tokenized one containing them). In addition, the tenant must have tracking enabled in its internal configuration; otherwise, the headers are ignored.

Published information

When the event is issued, it appears in the Security tab of the operation details with the following fields:

Field	Description
IAD Diagnostic	High-level result: Attack Not Detected, Attack Detected, or Error: <detail> if detection did not complete.
Request ID	Unique request identifier, useful for correlating with logs.
Version	Version of the IAD engine used. Only appears if the tenant has it configured.

The event is issued both on successes (Attack Detected / Attack Not Detected) and on errors (engine failure, timeout, invalid bundle), so that any IAD invocation is recorded with its high-level result. Internal details of the engine or the bundle are not exposed: the event contains only the high-level result and the identifiers needed for auditing.

Client-side integration

To generate the encrypted blob payload, it is necessary to use the version of the Selphi Antispoof Widget and capture the event onExtractionFinished. The event will return an object with the results of the facial extraction process. One of the properties of this object is encryptedLivenessRaw, which contains the encrypted blob payload.

Once the payload is obtained, it must be sent to the client's server via a POST request. Any HTTP client library can be used, such as Axios or Fetch.

The client's server must receive this payload and send it to the Identity API IAD endpoint. The API will return the results in a JSON object indicating whether it passes the validations.

Integration example

const onExtractionFinished = (extractionResult) => {
  fetch(YOUR_BACKEND_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/octet-stream',
    },
    body: extractionResult.detail.encryptedLivenessRaw
  }).then(response => {
    return response.json();
  }).then(result => {
    console.log('RESULT FROM SERVICE', result);
  }).catch(e => {
    console.error(e);
  });
}