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

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 para mais detalhes.

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

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

Este JWT deve ser assinado com a client-secret.

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.

Generate Mobile Token (Session Token)

get

Returns a JWT token enriched with a unique session identifier.

Autorizações

customAuth

AuthorizationstringObrigatório

Authentication Token (JWT) signed with your client-secret

Respostas

200

JWT generated with session details

application/json

requestIdstringOpcionalExample: 123e4567-e89b-12d3-a456-426614174000

sessionTokenstringOpcionalExample: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

401

Invalid or missing token

application/json

500

Internal server error

application/json

get/session-tokens

HTTPcURL

GET /bff/session-tokens HTTP/1.1
Host: web.us.prd.caf.io
Authorization: YOUR_AUTHENTICATION_TOKEN

{
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

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

CafSDK

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

Confira Integração com o Android SDK para mais detalhes.

CerttaSDK

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

Confira Guia de Instalação do Android Certta SDK para mais detalhes.

4.2 iOS

CafSDK

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

Confira Integração com o SDK iOS para mais detalhes.

CerttaSDK

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

Confira Integração com o SDK iOS para mais detalhes.

4.3 Web

Web

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

Confira Integração com o SDK Web para mais detalhes.

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.

Veja Vinculação de transações para mais detalhes.

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.

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.