2. Getting Started

Prerequisites for Using the API

• Basic programming knowledge and familiarity with REST APIs.
• A development environment configured to perform HTTP requests.

2.1 API-KEY Permissioning

To ensure security, quality, and control of transactions performed in the FortFace environment, permissioning is based on an API-KEY. This is a key (UUID) sent in the request headers.

The API-KEY will have permissions enabled according to the commercial conditions contracted.

Permissions

Context	API	HTTP Methods	Version	Handshake Action
SDK	handshake	POST	V1	N/A
SDK	enroll	POST	V1	enroll
SDK	identify	POST	V1	identify
SDK	search	POST	V1	search
SDK	liveness	POST	V1	liveness
SDK	capture	POST	V1	capture
Backoffice	handshake	POST	V1	N/A
Backoffice	enroll	POST, PUT, DELETE	V1	enroll, update-enroll, delete-enroll
Backoffice	identify	POST	V1	identify
Backoffice	search	POST	V1	search
Backoffice	liveness	POST	V1	liveness
Backoffice	capture	POST	V1	capture
Backoffice	photo	GET	V1	N/A
Backoffice	log session	GET	V1	N/A

Preferred Backoffice flow: direct authentication with x-api-key on each request.

The /backoffice/v1/handshake endpoint remains available only for backward compatibility and is being deprecated.

2.2 Gallery Configuration

Image Storage

FortFace allows clients to organize stored photos flexibly according to their business context. To do so, clients may use one or more galleries, allowing photos to be stored under different operational contexts.

Currently, gallery creation and configuration are not available directly to clients. Similar to API-KEY permissions, galleries are created and configured based on contracted commercial agreements.

An important configuration to consider is the photo persistence behavior.

If the savePhoto flag is set to true, the image will be stored normally by FortFace, whether in the SDK or Backoffice context. However, if the flag is false, the following scenarios apply:

• SDK

  Requests made to SDK context APIs will always return the captured image in the response (base64 format) when savePhoto is false. This is because the client does not have direct access to the image captured by the SDK.
  Additionally, even if the client stores the image externally, they may still wish to receive it in the response. In this case, SDK APIs (enroll, identify, search, liveness) accept the returntPhoto property in the request.
  The default value is false, except when the photo is not saved. When returntPhoto is true, the photo will be included in the response in base64 format.

• Backoffice

  Requests made to Backoffice APIs will not return the photo, as the image is already provided in base64 format within the request body. Returning the same data would be redundant.

Automatic Update of Enrollment Photo for Users Migrated from Legacy Databases

FortFace provides an automatic update mechanism for user enrollment photos once the first successful identification is completed. The following conditions apply:

• The user originates from a legacy database migration (backoffice/enroll)
• The user is approved in the Liveness check
• The user completes the first successful transaction above the MatchLevel defined by the client

Once all criteria are met, the user’s enrollment photo is replaced with a more recent and higher-quality image captured through the FortFace SDK, improving overall system performance.

---

2.3 mTLS Certificates

To further enhance communication security between the client and FortFace, the mTLS certification process has been improved.

Clients must now generate the .csr (Certificate Signing Request) file locally and send it to FortFace.

After receiving the CSR, we return a signed certificate, ready for use in the integration.

To simplify the process, we provide a tool with detailed instructions for generating the certificate correctly:

👉 https://mtls-tool.fortface.com/

When your environment's HTTPS client supports it, prefer using a certificate (.crt or .pem) and a separate private key (.key) instead of a PFX file; in some environments, direct PFX usage can result in errors (for example: "Unsupported PKCS12 PFX data"). To extract the certificate from a PFX: openssl pkcs12 -in file.pfx -clcerts -nokeys -out certificate.crt -passin pass:PASSWORD. Use the .crt and .key in your HTTPS client options (and passphrase if the key is password-protected).