> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md).

# Configuração

Esta página percorre a integração do backend de ponta a ponta: do token de sessão que seu app precisa para iniciar o SDK até o resultado final de liveness.

![Fluxo de integração do backend: token de sessão, captura, validação de signedResponse, token de acesso e resultado](https://2463264195-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFXOsfB19xW3Mn4Vn5DeD%2Fuploads%2Fgit-blob-642c4ef157a4335301b5e8e9fec7b6c9ef586682%2Fface-liveness-lite-backend-flow.png?alt=media)

## Requisitos

| Requisito    | Usado para   | Descrição                                                                                                                                                                                                                                                                            |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Chave Mobile | Etapas 1 e 3 | `client-id` e `client-secret` da [Trust Platform](https://trust.caf.io/) (**Configurações** → **Configurações de API** → **Chaves Mobile**). Usado para solicitar o token de sessão e verificar o `signedResponse`. Veja [Autenticação](https://docs.caf.io/caf-sdk/authentication). |
| Aplicativo   | Etapas 4 e 5 | Um aplicativo da [Trust Platform](https://trust.caf.io/) (**Configurações** → **Configurações de API** → **Aplicações**) com credenciais OAuth2 (`client_id` e `client_secret`), usado para obter um token de acesso.                                                                |
| Permissão    | Etapa 5      | O escopo `v1-faces-liveness-attempts:read` concedido ao aplicativo.                                                                                                                                                                                                                  |

Os caminhos da Trust Platform acima se aplicam à região dos EUA. Para a região do Brasil, veja [Regiões](#regions).

{% hint style="warning" %}
Execute cada chamada para a Certta a partir do seu backend. Nunca coloque a Chave Mobile `client-secret`, o aplicativo `client_secret` ou um token de acesso no app.
{% endhint %}

{% hint style="info" %}
A Chave Mobile `client-secret` e o aplicativo `client_secret` são credenciais diferentes. A primeira assina o Token de autenticação e verifica o `signedResponse`; a segunda obtém o token de acesso para ler o resultado.
{% endhint %}

## Regiões

O Face Liveness Lite é executado em duas regiões isoladas. Escolha uma e use seus hosts em cada etapa.

| Host                              | EUA                         | Brasil                      |
| --------------------------------- | --------------------------- | --------------------------- |
| Web (token de sessão)             | `https://web.us.prd.caf.io` | `https://web.sa.prd.caf.io` |
| API (token de acesso e resultado) | `https://api.us.prd.caf.io` | `https://api.sa.prd.caf.io` |

{% hint style="warning" %}
As regiões são totalmente isoladas. Nada criado em uma região está disponível na outra:

* **Chaves** — use a Chave Mobile e as credenciais do aplicativo da região que você chamar.
* **Configurações do produto** — as configurações não são replicadas entre regiões.
* **Tentativas de liveness** — um `livenessAttemptId` criado em uma região não é encontrado na outra.

Todas as etapas de uma transação — token de sessão, captura e resultado — devem acontecer na mesma região.
{% endhint %}

Para usar a região do Brasil, entre em contato com a Certta. A Certta fornece a Chave Mobile e as credenciais do aplicativo para o Brasil.

O SDK seleciona a região a partir do token de sessão, então o app não precisa de configuração de região. Para as versões mínimas do SDK, veja [Regiões](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/vivacidade-facial-lite.md#regions).

{% stepper %}
{% step %}

## Solicite o token de sessão

Seu backend assina um Token de autenticação com a Chave Mobile e o troca por um token de sessão. Para ver todos os detalhes, consulte [Autenticação](https://docs.caf.io/caf-sdk/authentication).

O Token de autenticação é um JWT assinado com a Chave Mobile `client-secret`, com este payload:

| Reivindicação | Obrigatório | Descrição                                              |
| ------------- | ----------- | ------------------------------------------------------ |
| `iss`         | Sim         | A Chave Mobile `client-id`.                            |
| `exp`         | Não         | Tempo de expiração (timestamp Unix). Mantenha-o curto. |

```javascript
const jwt = require('jsonwebtoken');

const authenticationToken = jwt.sign({ iss: mobileKeyClientId }, mobileKeyClientSecret, {
  algorithm: 'HS256',
  expiresIn: '10m',
});
```

Envie-o para o endpoint do token de sessão:

|                 |                                                                                   |
| --------------- | --------------------------------------------------------------------------------- |
| **URL base**    | `https://web.us.prd.caf.io/bff` (EUA) ou `https://web.sa.prd.caf.io/bff` (Brasil) |
| **Caminho**     | `GET /session-tokens`                                                             |
| **Autorização** | `Bearer <AUTHENTICATION_TOKEN>`                                                   |

```bash
curl -X GET 'https://web.us.prd.caf.io/bff/session-tokens' \\
  -H 'Authorization: Bearer <AUTHENTICATION_TOKEN>'
```

### Resposta

```json
{
  "requestId": "string",
  "sessionToken": "string",
  "tokenId": "string"
}
```

| Campo          | Tipo   | Descrição                                                                                                      |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| `requestId`    | String | Identificador desta solicitação. Use-o ao entrar em contato com o suporte.                                     |
| `sessionToken` | String | Token usado para iniciar o SDK no app.                                                                         |
| `tokenId`      | String | Identificador do token emitido. **Armazene-o** — você precisa dele para validar o `signedResponse` na etapa 3. |

Envie o `sessionToken` para o app e mantenha o `tokenId` no seu backend, vinculado à jornada do usuário. O app passa o `sessionToken` para o SDK como `mobileToken`, junto com o `personId`:

| Plataforma | Onde o `sessionToken` vai                                                                                                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iOS        | `setup(mobileToken:personId:…)` — veja [Iniciando o fluxo de liveness](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/configuration/starting-liveness-flow.md)          |
| Android    | `CafLivenessConfig(mobileToken = …)` — veja [Iniciando o fluxo de liveness](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/android/configuration/starting-liveness-flow.md) |

Solicite um novo token de sessão logo antes de cada tentativa de liveness. Trate cada `tokenId` como uso único: seu backend aceita apenas um `signedResponse` para ele (veja a etapa 3).
{% endstep %}

{% step %}

## Receba o `signedResponse`

Quando a captura termina, o SDK retorna um `signedResponse` para o seu app, que deve encaminhá-lo ao seu backend. Ele é retornado em caso de sucesso e de falha:

| Plataforma | Sucesso                                     | Falha                                                          |
| ---------- | ------------------------------------------- | -------------------------------------------------------------- |
| iOS        | `didFinishWithSuccess(livenessResult:)`     | `didFinishWithFailure(type:description:signedResponse:)`       |
| Android    | `LivenessLiteEvent.Success(signedResponse)` | `LivenessLiteEvent.Failure(signedResponse, type, description)` |

O `signedResponse` é um JWT assinado. Seu payload contém:

```json
{
  "livenessAttemptId": "string",
  "tokenId": "string",
  "sessionId": "string",
  "personId": "string"
}
```

| Campo               | Tipo   | Descrição                                                                                                        |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `livenessAttemptId` | String | Identificador único da tentativa de liveness. Usado para recuperar o resultado na etapa 5.                       |
| `tokenId`           | String | Identificador do token de sessão que iniciou esta captura. Deve corresponder ao `tokenId` armazenado na etapa 1. |
| `sessionId`         | String | Identificador da sessão de liveness registrada.                                                                  |
| `personId`          | String | Identificador da pessoa associada à tentativa.                                                                   |

{% hint style="info" %}
O `signedResponse` não contém `isAlive` nem imagens. O SDK também não espera pelo resultado: seu backend o recupera na etapa 5.
{% endhint %}
{% endstep %}

{% step %}

## Valide o `signedResponse`

Antes de usar qualquer valor do payload, verifique:

1. **Assinatura** — o JWT é verificado com sua Chave Mobile `client-secret`, usando apenas o `HS256` algoritmo.
2. **`tokenId`** — ele está presente e é igual ao `tokenId` que você armazenou na etapa 1.
3. **Uso único** — o `tokenId` não foi usado antes. Marque-o como usado na mesma operação que esta verificação, para que duas solicitações concorrentes não possam ambas passar.
4. **`personId`** (opcional) — ele é igual ao `personId` que seu app passou para o SDK.

Se uma verificação falhar, rejeite o `signedResponse`. Veja [Tratamento de erros](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/backend/error-handling.md#validation-errors). O payload não tem `exp` claim: não exija um.

Exemplo em Node.js, com a biblioteca [`jsonwebtoken`](https://www.npmjs.com/package/jsonwebtoken) sua biblioteca:

```javascript
const jwt = require('jsonwebtoken');

// `session` is the record your backend stored in step 1: { tokenId, personId, used }
function validateSignedResponse(signedResponse, session, mobileKeyClientSecret) {
  const payload = jwt.verify(signedResponse, mobileKeyClientSecret, { algorithms: ['HS256'] });

  if (!payload.tokenId || payload.tokenId !== session.tokenId) {
    throw new Error('tokenId missing or mismatch');
  }

  if (session.used) {
    throw new Error('tokenId already used');
  }

  // Opcional
  if (payload.personId !== session.personId) {
    throw new Error('personId mismatch');
  }

  // Persista isso na mesma operação atômica da verificação acima
  session.used = true;

  return payload.livenessAttemptId;
}
```

{% endstep %}

{% step %}

## Obtenha um token de acesso

O endpoint de resultado usa OAuth2. Troque as credenciais do aplicativo por um token de acesso:

|                  |                                                                           |
| ---------------- | ------------------------------------------------------------------------- |
| **URL base**     | `https://api.us.prd.caf.io` (EUA) ou `https://api.sa.prd.caf.io` (Brasil) |
| **Caminho**      | `POST /oauth2/token`                                                      |
| **Content-Type** | `application/x-www-form-urlencoded`                                       |

| Campo do corpo  | Tipo   | Obrigatório | Descrição                        |
| --------------- | ------ | ----------- | -------------------------------- |
| `grant_type`    | String | Sim         | Valor fixo: `client_credentials` |
| `client_id`     | String | Sim         | ID do aplicativo                 |
| `client_secret` | String | Sim         | Segredo do aplicativo            |

Não envie um `scope` parâmetro. O token de acesso carrega os escopos concedidos ao aplicativo.

```bash
curl -X POST 'https://api.us.prd.caf.io/oauth2/token' \\
  -H 'Content-Type: application/x-www-form-urlencoded' \\
  -d 'grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>'
```

```json
{
  "access_token": "string",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

`expires_in` é o tempo de vida do token em segundos. Reutilize o token até ele expirar e, então, solicite um novo.
{% endstep %}

{% step %}

## Recupere o resultado

|              |                                                                           |
| ------------ | ------------------------------------------------------------------------- |
| **URL base** | `https://api.us.prd.caf.io` (EUA) ou `https://api.sa.prd.caf.io` (Brasil) |
| **Caminho**  | `GET /v1/faces/liveness/attempts/{attemptId}/await`                       |

Este endpoint aguarda no servidor até que a tentativa conclua o processamento e retorna o resultado em uma única chamada. Quando o resultado estiver pronto, a resposta traz um `status`: `COMPLETED` ou `FAILED`. Se o resultado não estiver pronto dentro do tempo de espera do servidor, o endpoint retorna `attempt_not_found`; veja [Tratamento de erros](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/backend/error-handling.md#result-errors).

### Parâmetros de caminho

| Parâmetro   | Tipo   | Obrigatório | Descrição                                                  |
| ----------- | ------ | ----------- | ---------------------------------------------------------- |
| `attemptId` | String | Sim         | O `livenessAttemptId` lido do `signedResponse` na etapa 3. |

### Cabeçalhos

| Cabeçalho     | Tipo   | Obrigatório | Descrição                                                                                          |
| ------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------- |
| `Autorização` | String | Sim         | `Bearer` token de acesso da etapa 4, de um aplicativo que tenha `v1-faces-liveness-attempts:read`. |

### Exemplo

```bash
curl -X GET \\
  'https://api.us.prd.caf.io/v1/faces/liveness/attempts/<LIVENESS_ATTEMPT_ID>/await' \\
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

### Tempo

* Defina o timeout do seu cliente HTTP acima de **15 segundos**: a chamada pode aguardar no servidor enquanto a tentativa é processada.
* Chame o endpoint assim que seu backend tiver o `livenessAttemptId`. Chamadas posteriores retornam o mesmo resultado, mas demoram mais.

Os campos da resposta são descritos em [Referência de resultados](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/result-reference.md). Para decidir o que fazer com o resultado, veja [Tratamento de falhas](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/backend/failure-handling.md).
{% endstep %}
{% endstepper %}

## Antes de entrar em produção

* [ ] Cada chamada para a Certta é executada no seu backend, e nenhum segredo está no app. Veja [Requisitos](#requirements).
* [ ] Você usa a Chave Mobile e as credenciais do aplicativo da região que você chamar, e todas as etapas usam a mesma região. Veja [Regiões](#regions).
* [ ] Você verifica o `signedResponse` com `HS256`, e o `tokenId` está presente, corresponde e é usado apenas uma vez. Veja [Valide o `signedResponse`](#validate-the-signedresponse).
* [ ] Você aprova apenas com base na resposta do endpoint de resultado, nunca no que o app informa. Veja [Tratamento de falhas](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/backend/failure-handling.md).
* [ ] Você trata cada resultado na tabela de decisão: vivo, não vivo, sem imagem utilizável e não concluído. Veja [Decidindo o resultado](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/backend/failure-handling.md#deciding-on-the-result).
* [ ] Você chama o endpoint de resultado mais uma vez quando recebe `attempt_not_found`. Veja [Erros de resultado](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/backend/error-handling.md#result-errors).
* [ ] O timeout do seu cliente HTTP está acima de 15 segundos. Veja [Recupere o resultado](#retrieve-the-result).
* [ ] Você reutiliza o token de acesso até ele expirar. Veja [Obtenha um token de acesso](#obtain-an-access-token).
* [ ] Você registra o `requestId` (ou o `x-amzn-RequestId` cabeçalho de resposta) para suporte. Veja [Entrando em contato com o suporte](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/backend/error-handling.md#contacting-support).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
