Autenticação facial

Autenticação Facial é um serviço biométrico que permite o registro facial e a autenticação por meio de comparação facial. Este recurso disponibiliza endpoints para registrar faces de pessoas e consultar tentativas de autenticação facial.

Requisitos de autenticação:

• Endpoints regulares usam OAuth2 autenticação com URL base: https://api.us.prd.caf.io
• Para maior segurança, alguns endpoints também podem suportar mTLS autenticação com URL base: https://mtls.us.prd.caf.io
• Para informações sobre a implementação de mTLS, acesse Usando mTLS

Registro Facial

O endpoint de registro permite associar uma imagem facial a um identificador de pessoa (personId), criando uma referência biométrica que será usada posteriormente para autenticação.

As faces registradas por este endpoint serão usadas para comparação facial por meio do CafSdk ou CafFaceLiveness SDKs. As SDKs documentadas como obsoletas não necessariamente usarão esses registros faciais.

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

Parâmetros de cabeçalho

AuthorizationstringObrigatório

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

Example: Bearer YOUR_TOKEN

Corpo

application/json

personIdstringObrigatório

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

imageUrlstringObrigatório

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

Respostas

200

Face registered successfully

application/json

requestIdstringObrigatório

Unique identifier of request

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

messagestringObrigatório

Status message

Example: Face registration in progress

personIdstringObrigatório

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"
}

Consulta de Tentativa de Autenticação Facial

O endpoint de consulta permite recuperar informações sobre uma tentativa específica de autenticação facial, incluindo as URLs das imagens usadas.

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

Parâmetros de rota

attemptIdstringObrigatório

Unique identifier of the authentication attempt.

Example: 01K1XDD6W98M5QM9B8EAZZDV49

Parâmetros de cabeçalho

AuthorizationstringObrigatório

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

Example: Bearer YOUR_TOKEN

Respostas

200

Attempt found successfully

application/json

requestIdstringObrigatório

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
  }
}