> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/security-compliance/injection-attack-detection.md). # 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 ```bash 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 ```json { "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](#códigos-de-error-iad). ```json { "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 ```json { "message": "Unauthorized" } ``` #### `403` Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Bad Gateway ```json { "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 ```json { "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: ` 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 ```javascript 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); }); } ```