Autenticação (obsoleto)

Autentique a API Mobile com sua chave de acesso para usar os recursos disponíveis.

Para acessar os recursos da CAF usando esta API REST, primeiro você precisará de uma Chave Mobile. Esse é um token que a CAF fornece para autorização e é usado pelo cliente ao fazer cada chamada à API.

As chaves de API são um segredo que apenas o cliente e a CAF conhecem. Assim como a autenticação Basic, a autenticação baseada em chave de API só é considerada segura se usada em conjunto com outros mecanismos de segurança, como HTTPS/SSL.

Obtendo suas chaves

Usuários da conta com as permissões adequadas poderão recuperar ou criar sua chave mobile na Trust Platform seguindo os passos abaixo:

1. Depois de fazer login na Trust Platform, clique no botão de configurações (ícone de engrenagem) na área de navegação do cliente e depois selecione "Integração de API" nas opções.
2. Certifique-se de que a aba ativa seja "Chaves Mobile", nesta página você pode ver suas chaves e os produtos vinculados. Clique em "copiar" para salvar na sua área de transferência.
3. Para criar uma nova, clique no botão "Nova chave" e selecione quais produtos o token poderá executar e um nome para a chave; depois clique em "Gerar chave". A página mostrará para você clientId e clientSecret, mantenha isso em segurança.

Se o ambiente usado for o ambiente de homologação (beta), as chaves de acesso devem ser geradas no mesmo ambiente: Trust Platform BETA.

Gerando seu token

Método recomendado

Os passos a seguir descrevem como você pode gerar tokens que são válidos apenas para um usuário específico. Esta é a forma recomendada de gerar e distribuir os 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 os campos {clientId}, {peopleId} e {expiresAt}
   • Todos os campos são altamente recomendados, você pode ver qual é obrigatório na parte inferior desta página
2. Assine o token com seu clientSecret;
3. Use este token para autenticar chamadas da API ou do SDK.

Exemplo:

Cabeçalho

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

Payload

{
    "iss": "{clientId}", // string
    "exp": {expiresAt}, // número
    "peopleId": "{peopleId}" // string
}

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

1. Acesse o site 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. Vá para Share JWT para copiar o token gerado para a área de transferência;
6. Use este token para autenticar chamadas da API ou do 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 Unix time)
peopleId	Não	O CPF (Cadastro de Pessoa Física) no 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.

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.