> 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/sdks/backend-sdk/iad/release_notes/3.0.0_release_notes.md).

# 3.0.0

**Release date:** September 25, 2026

## Overview

**Facephi IAD Service 3.0.0** is a major release that renews the public evaluation contract. The service verifies that each face capture comes from a legitimate device camera, has not been tampered with by intermediate software, was not generated in an untrusted environment, and contains no artifacts consistent with synthetic, replayed, or reproduced content. The result is now a **binary verdict** (`NoAttack` or `Attack`) accompanied by a transaction ID.

This version **is not backward compatible** with the 2.x series.

## Breaking changes

### Evaluation Endpoint

| Endpoint 2.x                         | Endpoint 3.0.0              |
| ------------------------------------ | --------------------------- |
| `POST /api/v1/iad/liveness/evaluate` | `POST /api/v1/iad/evaluate` |

The 2.x series route is no longer registered. `POST /api/v1/iad/extract` does not change.

### Correct evaluation response

| 2.x                                       | 3.0.0                    | What to do in the integration                                                      |
| ----------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------- |
| `diagnostic: "Live"`                      | `diagnostic: "NoAttack"` | Update the comparison that accepts the capture                                     |
| `diagnostic: "NoLive"`                    | `diagnostic: "Attack"`   | Update the rejection comparison                                                    |
| `reason`                                  | `reason`                 | No changes                                                                         |
| `probability`, `score`, `faceProbability` | Removed                  | Stop reading them                                                                  |
| `sdkDuration`, `queueDuration`            | Removed                  | Stop reading them; operation times can be retrieved from `GET /api/v1/iad/metrics` |
| —                                         | `transactionId`          | Store it as the evaluation reference                                               |
| —                                         | `timestamp`              | Use it as the evaluation time                                                      |

Response 3.0.0:

```json
{
  "diagnostic": "NoAttack",
  "reason": "None",
  "transactionId": "f58dccd4-f2ce-4057-a99b-4dc916015745",
  "timestamp": "2026-09-24T09:04:03.776Z"
}
```

The error response body format is unchanged, but some HTTP status codes have changed (see “Responses when the service is unavailable”).

### Responses when the service is unavailable

| Situation                                                                                | 2.x                                                                 | 3.0.0                                                                     |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `GET /api/v1/iad/health` with an invalid license                                         | HTTP `200`, `message` equals `Unhealthy: <motivo> (code: <código>)` | HTTP `503`, `message` equals `Invalid license: <motivo> (code: <código>)` |
| `GET /api/v1/iad/health` with the analysis engine unresponsive                           | HTTP `400`, `Engine health check failed: <detalle>`                 | HTTP `503`, `Engine health check failed: <detalle>`                       |
| `POST /api/v1/iad/evaluate` and `/evaluate/custom` with the analysis engine unresponsive | HTTP `400`, `ErrorProcessing`                                       | HTTP `503`, `Engine communication error: <detalle>`                       |
| `POST /api/v1/iad/extract` with the analysis engine unresponsive                         | HTTP `400`, `Engine communication error: Too many retries`          | HTTP `503`, `Engine communication error: <detalle>`                       |

Responses `503` have `error` equal to `ServiceUnavailable`. They indicate that the service cannot handle the request at that moment, not that the request or the capture is incorrect: treat them as temporary unavailability and retry later. Probes and monitoring that read `GET /api/v1/iad/health` must treat any response other than `200` as service unavailable.

### Operational metrics

In `GET /api/v1/iad/metrics`, the `quality.liveness` block is renamed `quality.detection`, and its counters `live` and `noLive` become `noAttack` and `attack`. The alert message `LOW_QUALITY` becomes `Recent evaluation results show degraded quality`. Dashboards and alert rules that read those keys must be updated.

Additionally, an `Attack` verdict no longer counts as a low-quality sample: detecting an attack means the service is working correctly, so it no longer triggers the `LOW_QUALITY` alert or puts the service in the `degraded`. `quality.summary.lowQualitySamples` and `LOW_QUALITY` now reflect only captures that the analysis engine could not evaluate (errors `NoneBecause*`, such as `NoneBecauseFaceNotFound`).

## What’s new

### Binary verdict with traceability

* `diagnostic` is the only field that determines whether a capture is accepted: `NoAttack` when no injection attack is detected, and `Attack` when one is detected.
* `transactionId` is a UUID v4 generated for each request, including retries with the same capture. It uniquely identifies the evaluation: save it in your logs so you can refer to it, for example, in a support inquiry.
* `timestamp` is the UTC time, in milliseconds, when the service started handling the request.

### Evaluation with an explicit pipeline

* New endpoint `POST /api/v1/iad/evaluate/custom`, which evaluates the capture in the same way as `POST /api/v1/iad/evaluate` but uses the analysis pipeline and calibration chosen by the client.
* Required multipart field `pipeline`: `iad_r01` or `iad_r00`.
* Optional multipart field `calibration`: `regular` (default) or `hardened`.
* The response is the same as that of `POST /api/v1/iad/evaluate`.
* The Docker image loads all pipeline and calibration combinations by default, so no additional configuration is required.

### Full Prometheus exposure

* `GET /api/v1/iad/metrics/prometheus` now publishes the same snapshot as `GET /api/v1/iad/metrics`: the service-specific blocks (identity, status, usage, quality, and alerts) are added to the HTTP-level series (prefix `facephi_`) with the prefix `facephi_iad_`.
* Classification and alert series publish all their possible values, with `0` when they are inactive, and timestamps are published as epoch seconds.
* The complete list of series is in the [service overview](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad.md).

### Recovery from analysis engine crashes

* If the analysis engine process exits (for example, because the system stops it due to a lack of memory), the service stops accepting requests, releases the license, and exits with code `1`. This allows the container's restart policy to restart the service and engine without manual intervention.
* If the engine exits during startup, the service exits without opening the port.
* If the engine stops responding but its process is still running, the service does not exit: `GET /api/v1/iad/health` and capture operations return HTTP `503` until the engine responds again.
* Configure a restart policy in your deployment (`restart: unless-stopped` in Docker Compose, `--restart unless-stopped` with `docker run`; in Kubernetes, the default pod policy already restarts the container). The [installation guide](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/installation/installation_instructions.md) includes an example of Kubernetes probes.

### Lower-cost health check

* `GET /api/v1/iad/health` reuses the most recent analysis engine check for `engine_health_max_age_seconds` (10 seconds by default; variable `FACEPHI_IAD_ENGINE_HEALTH_MAX_AGE_SECONDS`), so frequent checks by orchestrators and load balancers do not burden the engine.
* When the check expires, it is repeated with a single attempt lasting no more than 5 seconds, without the retries configured by `engine_max_retries`.

### License and capture operation errors

* `POST /api/v1/iad/evaluate`, `POST /api/v1/iad/evaluate/custom` and `POST /api/v1/iad/extract` check the license on every request. If it becomes invalid while the service is running, they return HTTP `400` with `Invalid license: <motivo> (code: <código>)` without analyzing the capture.
* `POST /api/v1/iad/extract` normalizes analysis engine errors in the same way as `/evaluate`: it returns the same `NoneBecause*` and `Replay attack detected`, and `ErrorFacialImage` for unclassified failures.

### More accurate operational metrics

* The classification `degraded` only considers server errors from the last 5 minutes, rather than any errors since startup.
* The error rate at which the service is classified and `HIGH_ERROR_RATE` is triggered deducts rejected captures with `Replay attack detected`.
* The `traffic` windows include `clientErrors`, `serverErrors` and `unauthorized`, also published in Prometheus.
* With an invalid license, `/metrics` reports only the `LICENSE_EXPIRED`alert, without also marking the analysis engine as unavailable.

### JWT validation

* When JWT authentication is enabled, validation tolerates a 60-second clock skew when checking `exp` and `nbf`, so a token issued by a system whose clock is slightly ahead is no longer rejected. As a result, a token continues to be accepted for up to 60 seconds after it expires.
* Tokens that are not yet valid are rejected with HTTP `401` and the message `JWT token is not yet valid`, rather than being treated as expired.

## Fixes

* The service's memory usage no longer grows with each request. In previous versions, the service kept all the analysis engine's output in memory while it was running; each invalid capture adds about 20 KB to that output, so with many invalid captures, memory usage grew without limit and could exhaust the container's memory.
* The service no longer keeps running without an analysis engine when the engine process exits. In previous versions, it continued accepting requests and responding with errors until the container was manually restarted (see “Recovering from analysis engine crashes”).
* `GET /api/v1/iad/config` with the service uninitialized and `POST /api/v1/iad/config` with a `config_json_string` that cannot be loaded respond with HTTP `400` instead of `500`.

## Migration guide (from 2.x)

1. Change the evaluation URL to `POST /api/v1/iad/evaluate`.
2. Replace comparisons with `Live` and `NoLive` with `NoAttack` and `Attack`. Treat any value of `diagnostic` different from `NoAttack`.
3. Stop reading `probability`, `score`, `faceProbability`, `sdkDuration` and `queueDuration` in the evaluation response.
4. Log `transactionId` in your logs and send it to your backend to trace each evaluation.
5. Prepare response parsing to ignore unknown fields.
6. Update dashboards and alerts that read `quality.liveness` in `GET /api/v1/iad/metrics`.
7. Treat HTTP responses `503` from capture operations as temporary service unavailability and retry later.
8. Review the probes and monitoring for `GET /api/v1/iad/health`: it now responds `503` when the service cannot handle evaluations, including when the license is invalid.
9. Configure a restart policy in your deployment so the container recovers if the analysis engine stops.
10. Validate the integration with `GET /api/v1/iad/version` and end-to-end tests in your environment.

## Deployment

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:v3.0.0

docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:v3.0.0
```

Add `--restart unless-stopped`, or your orchestrator’s equivalent restart policy, so the container recovers if the analysis engine stops.

## Requirements

| Component        | Requirement                                                                                                                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operating system | Linux x86\_64 (Ubuntu 24.04 recommended)                                                                                                                                                                                            |
| License          | Valid Facephi License file                                                                                                                                                                                                          |
| Docker           | For containerized deployments                                                                                                                                                                                                       |
| Memory           | At least 6 GB per instance and 8 GB recommended for production (see [Memory sizing](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/technical_specifications.md#dimensionamiento-de-memoria)) |

## Known issues

* Because the built-in engine loads all pipeline and calibration combinations, memory usage and container startup time are higher than in the 2.x series: about 3.7 GB at rest and up to about 5.3 GB with concurrent evaluations. See [memory sizing](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/technical_specifications.md#dimensionamiento-de-memoria).

## Support

For Technical Support, contact your Facephi representative.

## Documentation

* [Service overview](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad.md)
* [Installation Guide](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/installation/installation_instructions.md)
* [API Reference](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/api_reference.md)
* [Changelog](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/changelog.md)
