> 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/caf-sdk/caf-sdk-pt-br/authentication.md).

# Autenticação

Este guia explica como autenticar os SDKs da Caf de forma segura e eficiente.

## Visão geral da integração

1. Obter credenciais de acesso (**Mobile Key**)
2. Gerar o **Token de Autenticação** (JWT assinado com seu `client-secret`)
3. Troque este token por um **Mobile Token** (Token de Sessão)
4. Use o **Mobile Token** ao inicializar o SDK

{% hint style="warning" %}
Para clientes que usam SDKs da Caf e que posteriormente criam transações para realizar validações adicionais, você terá uma etapa adicional: vincule o **Mobile Token** a uma transação, enviando-o como um `referenceToken` na solicitação de criação para permitir o rastreamento completo da jornada do usuário. Confira [Vinculação de transações](https://docs.caf.io/caf-api/core-api/transaction-linking) para mais detalhes.
{% endhint %}

## 1. Obtenha credenciais de acesso (Mobile Key)

As Mobile Keys são usadas para assinar e autenticar solicitações.

**Como obter:**

1. Acesse a [Trust Platform](https://trust.caf.io)
2. Navegue até **Configurações** → **Configurações da API (aba "Mobile Keys")**
3. Copie uma chave existente ou crie uma nova, especificando os produtos e o nome da chave.

## 2. Gere o Token de Autenticação (JWT)

Este JWT é gerado no seu servidor e assinado com a `client-secret`.

#### Campos do payload:

| Campo | Obrigatório | Descrição                            |
| ----- | ----------- | ------------------------------------ |
| `iss` | Sim         | Seu `client-id` (fornecido pela CAF) |
| `exp` | Não         | Expiração do token (timestamp Unix)  |

#### Exemplo de payload:

```json
{
  "iss": "your-client-id",
  "exp": 1728000000
}
```

{% hint style="warning" %}
Este JWT deve ser assinado com a `client-secret`.
{% endhint %}

## 3. Troque o Token de Autenticação por um Mobile Token

Depois de gerar o JWT, você deve trocá-lo pelo **Mobile Token**, que será usado para inicializar o SDK. Para cada sessão do SDK em seu aplicativo, gere um Mobile Token usando o Token de Autenticação criado anteriormente.

{% openapi src="/files/84e1daa24ca87711f95fe16a06797959aebc906a" path="/session-tokens" method="get" %}
[bff-openapi.yaml](https://3587114208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvnCLbngSdfkIVoF3ziNX%2Fuploads%2Fgit-blob-ea7014f435de65ce780257618d1bbc5febe6ce52%2Fbff-openapi.yaml?alt=media)
{% endopenapi %}

## 4. Use o Mobile Token no SDK

O `mobile-token` (Token de Sessão) é usado durante a **inicialização do SDK** e garante que cada sessão seja autenticada com segurança e rastreável.

Abaixo está como integrá-lo em diferentes plataformas:

### 4.1 Android

{% tabs %}
{% tab title="CafSDK" %}

```swift
val sdkBuilder = CafSdkProvider.Builder(
    mobileToken = "mobile-token",
).build()
```

Confira [Integração com o Android SDK](/caf-sdk/caf-sdk-pt-br/android/getting-started-with-the-sdk-1.md) para mais detalhes.
{% endtab %}

{% tab title="CerttaSDK" %}

```kotlin
Certta.instance.updateMobileToken("new-jwt-token")
```

Confira [Guia de Instalação do Android Certta SDK](/caf-sdk/caf-sdk-pt-br/android/installation-guide.md) para mais detalhes.
{% endtab %}
{% endtabs %}

### 4.2 iOS

{% tabs %}
{% tab title="CafSDK" %}

```swift
let builder = CafSDKProvider.Builder(
    self,
    mobileToken: "yourToken",
)
```

Confira [Integração com o SDK iOS](https://docs.caf.io/caf-sdk/ios/getting-started-with-the-sdk#builder-initialization) para mais detalhes.
{% endtab %}

{% tab title="CerttaSDK" %}

```kotlin
Certta.shared.updateMobileToken("new-jwt-token")
```

Confira [Integração com o SDK iOS](https://docs.caf.io/caf-sdk/ios/getting-started-with-the-sdk#builder-initialization) para mais detalhes.
{% endtab %}
{% endtabs %}

### 4.3 Web

{% tabs %}
{% tab title="Web" %}

```js
const builder = await CafSdkProvider.initializeSdk(
  "mobile-token",
  ...
);
```

Confira [Integração com o SDK Web](https://docs.caf.io/caf-sdk/web-javascript/getting-started/document-detector/documentdetector#xtquz7g7g6lm) para mais detalhes.
{% endtab %}
{% endtabs %}

## Vinculação de transações

Para garantir a segurança e a rastreabilidade completa da jornada do usuário, cada transação criada via API deve ser vinculada à sessão original gerada pelo SDK. Esse vínculo é feito incluindo o Mobile Token (token de sessão) em suas chamadas, criando uma trilha de auditoria unificada.

{% hint style="info" %}
Veja [Vinculação de transações](https://docs.caf.io/caf-api/core-api/transaction-linking) para mais detalhes.
{% endhint %}

## Melhores práticas para autenticação baseada em token

Para garantir uma integração segura e confiável ao usar autenticação baseada em token com nosso serviço, siga estas práticas recomendadas e evite erros comuns.

### ✅ Práticas recomendadas

| Prática                                                                   | Descrição                                                                                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Gerar e assinar tokens no servidor**                                    | Sempre emita JWTs do seu sistema de backend confiável para evitar expor chaves de assinatura.                                   |
| **Troque o JWT no `/session-tokens` endpoint antes de inicializar o SDK** | Use o `/session-tokens` endpoint para trocar o JWT assinado e obter um token de sessão de curta duração antes de iniciar o SDK. |
| **Use tempos de expiração curtos para JWTs**                              | Limite a vida útil do token para reduzir o impacto de uma possível exposição ou uso indevido.                                   |
| **Valide as respostas do SDK no backend usando o `client-secret`**        | Realize a validação das respostas do SDK no lado do servidor para garantir a autenticidade e a integridade dos dados.           |

### ❌ Práticas inseguras

| Prática                                                                | Risco                                                                                         |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Gerar tokens no frontend**                                           | Expõe suas chaves de assinatura e compromete todo o sistema de autenticação.                  |
| **Armazenar chaves de assinatura ou segredos em apps frontend/mobile** | Segredos no código do lado do cliente podem ser extraídos e usados indevidamente.             |
| **Codificar segredos diretamente no código sob controle de versão**    | Segredos em repositórios de código podem vazar ou ser acessados por usuários não autorizados. |
| **Reutilizar tokens de longa duração em várias sessões**               | Aumenta o risco e o raio de impacto caso um token seja exposto ou comprometido.               |

{% hint style="warning" %}
**Aviso importante sobre Autenticação e Integrações**

Todas as integrações com APIs da Caf devem ser implementadas exclusivamente via backend/lado do servidor. Integrações baseadas no lado do cliente ou no frontend podem ser bloqueadas e aumentar significativamente o risco de exposição da chave de autenticação.

A Caf monitora continuamente o uso e a exposição das chaves de autenticação. Qualquer chave identificada como exposta, comprometida ou usada em implementações não compatíveis será revogada imediatamente, o que pode resultar na interrupção da operação associada, sem aviso prévio.

É responsabilidade do integrador garantir a conformidade com os padrões de autenticação recomendados e as melhores práticas de segurança descritas nesta documentação.
{% endhint %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.