Face Authentication

Face Authentication is a biometric service that enables face registration and authentication through facial comparison. This resource provides endpoints to register faces for individuals and query facial authentication attempts.

Authentication Requirements:

• Regular endpoints use OAuth2 authentication with base URL: https://api.us.prd.caf.io
• For enhanced security, some endpoints may also support mTLS authentication with base URL: https://mtls.us.prd.caf.io
• For information on implementing mTLS, access Using mTLS

Face Registration

The registration endpoint allows associating a facial image with a person identifier (personId), creating a biometric reference that will be used later for authentication.

Faces registered by this endpoint will be used for facial comparison through the CafSdk or CafFaceLiveness SDKs. SDKs documented as deprecated will not necessarily use these facial registrations.

Register Face

post

https://api.us.prd.caf.io/v1/faceshttps://mtls.us.prd.caf.io/v1/faces

/

Register a facial image for a person identifier, creating a biometric reference for future authentication.

Permission required: Create Face Authentication

Header parameters

AuthorizationstringRequired

Your access token. See more in the 'Authentication' topic of this section.

Example: Bearer YOUR_TOKEN

Body

application/json

personIdstringRequired

Unique person identifier (CPF, external ID, etc). Must be between 5 and 254 characters and contain only letters, numbers and special characters "@", ".", "_", "-". If personId contains only numbers and the symbols ".", "-", "/", these special characters are removed, as the value is interpreted as a document mask.

Example: 12345678901

imageUrlstringRequired

URL of the facial image to be registered. Must be a valid and accessible .jpg or .png URL

Example: https://example.com/face-image.png

Responses

200

Face registered successfully

application/json

requestIdstringRequired

Unique identifier of request

Example: bb1ce1fd-5d0d-42af-bb0e-16f56b230a20

messagestringRequired

Status message

Example: Face registration in progress

personIdstringRequired

Person identifier

Example: 12345678901

400

Invalid request data

application/json

401

Invalid authentication token

application/json

403

The token does not have permission to access this resource

application/json

422

Unsupported image format

application/json

500

Internal server error

application/json

post/

HTTPcURLJavaScriptPython

POST /v1/faces/ HTTP/1.1
Host: api.us.prd.caf.io
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "personId": "12345678901",
  "imageUrl": "https://example.com/face-image.png"
}

{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "message": "Face registration in progress",
  "personId": "12345678901"
}

Face Authentication Attempt Query

The query endpoint allows retrieving information about a specific facial authentication attempt, including URLs of the images used.

Query Attempt

get

https://api.us.prd.caf.io/v1/faceshttps://mtls.us.prd.caf.io/v1/faces

/attempts/{attemptId}

Retrieve information about a specific facial authentication attempt, including URLs of the images used.

Permission required: Read Face Authentication Attempts

Path parameters

attemptIdstringRequired

Unique identifier of the authentication attempt.

Example: 01K1XDD6W98M5QM9B8EAZZDV49

Header parameters

AuthorizationstringRequired

Your access token. See more in the 'Authentication' topic of this section.

Example: Bearer YOUR_TOKEN

Responses

200

Attempt found successfully

application/json

requestIdstringRequired

Unique identifier of request

Example: bb1ce1fd-5d0d-42af-bb0e-16f56b230a20

400

attemptId not provided

application/json

401

Invalid authentication token

application/json

403

The token does not have permission to access this resource

application/json

404

Attempt not found

application/json

500

Internal server error

application/json

get/attempts/{attemptId}

HTTPcURLJavaScriptPython

GET /v1/faces/attempts/{attemptId} HTTP/1.1
Host: api.us.prd.caf.io
Authorization: text
Accept: */*

{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "data": {
    "id": "01K1XDD6W98M5QM9B8EAZZDV49",
    "createdAt": "2025-07-15T10:30:00.000Z",
    "personId": "12345678901",
    "sourceIp": "192.168.1.100",
    "registeredFaceImageUrl": "https://s3.amazonaws.com/bucket/registered-face.jpg?signature=...",
    "capturedFaceImageUrl": "https://s3.amazonaws.com/bucket/captured-face.jpg?signature=...",
    "isMatch": true,
    "similarity": 0.95
  }
}