> 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.md).

# Identity API reference

This document includes the specification of the services exposed in SaaS mode through Facephi's REST APIs for the Onboarding and Authentication products.

#### API Access

| Parameter | Value                              |
| --------- | ---------------------------------- |
| Host      | <https://api.identity-platform.io> |

#### Authorizations

All calls to the Endpoints must include the following keys in the request header:

| Key         | Value                        | Required |
| ----------- | ---------------------------- | -------- |
| `x-api-key` | Access authorization API key | **Yes**  |

If the required keys mentioned above are not included or are not valid, the request is rejected by the **gateway before reaching the service**. These responses are the default responses of AWS API Gateway and **do not** use the envelope `serviceResultCode`:

| HTTP code | Response body                                                                         | Case                                              |
| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------- |
| 401       | `{"message": "Unauthorized"}`                                                         | API Key missing or invalid.                       |
| 403       | `{"Message": "User is not authorized to access this resource with an explicit deny"}` | Valid API Key but without access to the resource. |

{% hint style="info" %}
The capitalization of the field differs between both responses (`message` in the `401`, `Message` in the `403`): they are the default bodies of AWS API Gateway.
{% endhint %}

#### Integration with Identity Platform

{% hint style="info" %}
All calls to the Endpoints for tracking with Identity Platform must contain the following header:
{% endhint %}

| Key      | Value                                                                                                                                           |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `family` | **Onboarding** — For all calls related to Digital Onboarding processes. **Authentication** — For all calls related to Authentication processes. |

#### Service response time

| Process        | Estimated / average time                                        | Notes                                                                       |
| -------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| liveness check | Processing < 1 second + network latency between 2 and 4 seconds | The total perceived time depends on the network hop.                        |
| Face match     | Processing < 1 second + network latency between 2 and 4 seconds | Similar to the liveness check, it depends on connectivity.                  |
| Civil registry | Typically < 10 seconds                                          | The registry does not commit to a formal response-time SLA.                 |
| Morphology     | Average: 60 seconds. Maximum: 270 seconds                       | Semi-automated process; varies depending on load and processing conditions. |