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

## 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 Connect           | Etapas 4 e 5 | Uma aplicação na Trust com credenciais OAuth2 (`client_id` e `client_secret`), usada para obter um token de acesso.                                                                                                                                                                  |
| Permissão                    | Etapa 5      | O escopo `v1-faces-liveness-attempts:read` concedido ao aplicativo Connect.                                                                                                                                                                                                          |
| Tempo limite do cliente HTTP | Etapa 5      | Maior que **15 segundos**. O endpoint de resultado aguarda no servidor até que o resultado esteja pronto.                                                                                                                                                                            |

{% hint style="info" %}
A Chave Mobile `client-secret` e a aplicação Connect `client_secret` são credenciais diferentes. A primeira 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 todas as etapas.

| 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 Chaves Mobile e aplicações Connect emitidas na região que você usar.
* **Configurações do produto** — as configurações não são replicadas entre as 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 %}

O SDK seleciona a região automaticamente, com base na região em que o token de sessão foi emitido. Nenhuma configuração de região é necessária no app. Isso requer as versões mínimas abaixo:

| Plataforma      | Versão mínima |
| --------------- | ------------- |
| iOS (CafSDKiOS) | 7.8.0         |
| Android         | 7.27.0        |

{% stepper %}
{% step %}

## Solicite o token de sessão

Seu backend troca um Token de autenticação, assinado com a Chave Mobile `client-secret`, por um token de sessão. A solicitação completa está descrita em [Autenticação](https://docs.caf.io/caf-sdk/authentication).

|              |                                                                                   |
| ------------ | --------------------------------------------------------------------------------- |
| **URL base** | `https://web.us.prd.caf.io/bff` (EUA) ou `https://web.sa.prd.caf.io/bff` (Brasil) |
| **Caminho**  | `GET /session-tokens`                                                             |

### Resposta

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

| Campo          | Tipo   | Descrição                                                                                                      |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| `requestId`    | String | Identificador desta solicitação. Use-o quando contatar 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 repassa o `sessionToken` para o SDK como `mobileToken`, junto com o `personId`:

| Plataforma | Onde o `sessionToken` vai                                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iOS        | <p><code>setup(mobileToken:personId:…)</code><br> — veja <a href="/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/start-sdk.md">Iniciar SDK</a></p>                      |
| Android    | `CafLivenessConfig(mobileToken = …)` — veja [Iniciando o fluxo de liveness](/sdk-lite/sdk-lite-english-pt-br/configuracao/android/configuration/starting-liveness-flow.md) |

Solicite um novo token de sessão imediatamente antes de cada tentativa de liveness. Reutilizar um token antigo, ou um token de outro ambiente, faz o SDK retornar um erro de token.
{% endstep %}

{% step %}

## Receba o `signedResponse`

Quando a captura termina, o SDK retorna um `signedResponse` para o seu app, que deve encaminhá-lo para o seu backend. Ele é retornado no sucesso e na 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 exclusivo 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 o resultado: seu backend o recupera na etapa 5.
{% endhint %}
{% endstep %}

{% step %}

## Valide o `signedResponse`

Antes de usar qualquer valor do payload:

1. **Verifique a assinatura** do JWT com sua Chave Mobile `client-secret`. Se a verificação falhar, não confie no payload.
2. **Compare o `tokenId`** no payload com o `tokenId` que você armazenou na etapa 1. Se não corresponderem, rejeite o `signedResponse`.
3. **Leia o `livenessAttemptId`** do payload verificado.

O `tokenId` Essa verificação é o que vincula a resposta emitida pelo SDK à sessão criada pelo seu backend. Veja [Tratamento de erros](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/backend/handling-errors.md#validation-errors) para saber o que fazer quando uma verificação falhar.
{% endstep %}

{% step %}

## Obtenha um token de acesso

O endpoint de resultado usa OAuth2. Troque as credenciais da aplicação Connect 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 da aplicação Connect          |
| `client_secret` | String | Sim         | Segredo da aplicação Connect     |

```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` é a duração do token em segundos. Solicite um novo token após ele expirar.
{% endstep %}

{% step %}

## Recupere o resultado

```
GET https://api.us.prd.caf.io/v1/faces/liveness/attempts/{attemptId}/await
```

Este endpoint aguarda no servidor até que a tentativa conclua o processamento e retorna o resultado final em uma única chamada. A resposta sempre carrega um status final `status`: `COMPLETED` ou `FAILED`.

### Parâmetros de caminho

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

### Cabeçalhos

| Cabeçalho       | Tipo   | Obrigatório | Descrição                                                                                        |
| --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------ |
| `Authorization` | String | Sim         | `Bearer` token de acesso da etapa 4, de uma aplicação que tem `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 de resposta

O resultado é mantido em cache por **2 minutos** após ficar disponível. Chame o endpoint assim que seu backend tiver o `livenessAttemptId` para obter a resposta mais rápida. Após essa janela, a mesma chamada ainda retorna o mesmo resultado, mas demora mais.

Defina o tempo limite do seu cliente HTTP acima de **15 segundos**, porque a chamada pode aguardar no servidor enquanto a tentativa é processada.

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


---

# 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.