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

# Autenticação

Para usar a API de Autenticações do Smart Auth, você precisará gerar um token de acesso do Smart Auth. Esta página mostra as etapas de como criar a chave, gerar os tokens de acesso e as maneiras recomendadas de fazer isso.

## **Obtendo sua chave do Smart Auth**

1. Acesse a [página de tokens do Smart Auth](https://identity.combateafraude.com/tokens);
2. Se você não tiver um token, gere um.
3. Recupere o `clientId` e `clientSecret` de um dos tokens gerados.

{% hint style="info" %}
Você pode repetir este procedimento para gerar acessos combinando diferentes funções e SDKs.
{% endhint %}

## **Gerando seu token**

### **Método recomendado**

As etapas a seguir descrevem como você pode gerar um token que é válido apenas para um usuário específico. Esta é a maneira recomendada de gerar e distribuir tokens porque limita um possível ataque a uma única conta de usuário.

1. Em algum ponto do fluxo da sua aplicação, crie um JWT com a estrutura do exemplo abaixo;
   * Lembre-se de substituir o `{clientId}`, `{personId}` e `{expiresAt}` campos.
   * Todos esses campos são fortemente recomendados, mas você pode ver quais são obrigatórios na parte inferior desta página.
2. Assine o token com seu `clientSecret`;
3. Envie este token para sua aplicação.

**Exemplo:**

{% tabs %}
{% tab title="Cabeçalho" %}

```json
{
  "alg": "HS256",
  "typ": "JWT"
}
```

{% endtab %}

{% tab title="Payload" %}

```json
{
    "iss": "{clientId}", // string
    "exp": {expiresAt}, // número
    "personId": "{personId}" // string
}
```

{% endtab %}
{% endtabs %}

### **Método não recomendado (apenas para testes)**

1. Vá para [jwt.io](https://jwt.io/);
2. Mantenha o **Cabeçalho** campo, não altere;
3. Edite o payload, apenas o campo `iss` é obrigatório;
4. Substitua \*\*\*\* `your-256-bit-secret` pelo seu `clientSecret`;
5. Clique **Share JWT** para copiar o token gerado para a área de transferência;
6. Use este token para autenticar o SDK.

### **Parâmetros do payload do JWT**

| Parâmetro      | Obrigatório | Descrição                                                                                |
| -------------- | ----------- | ---------------------------------------------------------------------------------------- |
| **`iss`**      | Sim         | Seu `clientId`                                                                           |
| **`exp`**      | Não         | Tempo de expiração (segundos desde a [Era Unix](https://pt.wikipedia.org/wiki/Era_Unix)) |
| **`personId`** | Não         | O CPF (Cadastro de Pessoa Física) para o qual o token será válido                        |

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

### ✅ Práticas recomendadas

| Prática                                         | Descrição                                                                                                                     |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Gere e assine tokens no servidor**            | Emita sempre JWTs a partir do seu sistema de backend confiável para evitar expor chaves de assinatura.                        |
| **Use HTTPS para todas as comunicações**        | Evite ataques man-in-the-middle e garanta criptografia em trânsito.                                                           |
| **Use tempos de expiração curtos para JWTs**    | Minimize a janela para uso indevido do token em caso de interceptação. Os tokens normalmente devem expirar em poucos minutos. |
| **Monitore o uso e o comportamento dos tokens** | Implemente registro e monitoramento para detectar atividades anormais ou suspeitas.                                           |

### ❌ 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.             |
| **Usando tokens de longa duração**                                     | Aumenta a janela de vulnerabilidade em caso de vazamento.                                     |
| **Codificar segredos diretamente no código versionado**                | Segredos em repositórios de código podem vazar ou ser acessados por usuários não autorizados. |

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

Todas as integrações com as APIs da Caf devem ser implementadas exclusivamente via backend/lado do servidor. Integrações no lado do cliente ou baseadas em frontend podem ser bloqueadas e aumentam 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 conformes será revogada imediatamente, o que pode resultar na interrupção da operação associada, sem aviso prévio.

É responsabilidade do integrador garantir 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-api/caf-api-pt-br/smart-auth-api/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.