Segurança

Como a FortunCred API protege as integrações dos parceiros — e o que cabe a você para manter a integração segura.

Por que API Key (e não OAuth/mTLS)?

A autenticação da FortunCred é por API Key (header X-API-Key), e isso é uma escolha deliberada. Bancos usam OAuth2 + certificado (mTLS) porque são regulados (Open Banking / FAPI) e movimentam dinheiro diretamente. A FortunCred é uma fachada sobre o nosso sistema: o modelo de risco é "proteger a chave", e isso é coberto por rotação + escopos + rate limit + homologação.

O resultado é uma integração muito mais rápida: sem baixar certificado, sem implementar troca de token. A segurança vem das camadas abaixo.

Padrão de mercado. APIs não-bancárias de referência (Stripe, Twilio, SendGrid) nasceram com chave/bearer simples. É a escolha adequada para este tipo de produto.

Como proteger sua chave

Faça	Não faça
Guarde a chave em variável de ambiente (server-side).	Não coloque a chave em app mobile, front-end ou repositório.
Use HTTPS sempre (a API só aceita HTTPS).	Não envie a chave por e-mail/chat aberto.
Restrinja a chave aos escopos que você usa.	Não compartilhe a mesma chave entre sistemas diferentes.
Ao suspeitar de vazamento, peça rotação imediata.	Não deixe chaves antigas ativas "por garantia".

Vazou? Avise o gestor: ele rotaciona a chave no painel e a antiga para de valer na hora. A rotação é instantânea.

Camadas de proteção da API

Camada	O que faz
Escopos	A chave pode ser limitada a `lead`, `simulacao`, `analise`, `acompanhamento`. Fora do escopo → `403 sem_permissao`.
Rate limit	Limite por parceiro (padrão 120 req/min). Excesso → `429 rate_limited` com `Retry-After`.
Isolamento por unidade	Cada chave só enxerga os leads/análises da própria unidade. Tentar acessar recurso de outra → `404` (nem confirma que existe).
Idempotência	`Idempotency-Key` obrigatória em `/analises` — evita disparo duplicado em retries.
Consentimento (LGPD)	Análise só com consentimento do titular, registrado de forma auditável.
Webhooks assinados	Cada entrega vem com assinatura HMAC-SHA256 — você valida a origem antes de confiar no payload.

Validando a assinatura do webhook

Toda entrega traz dois headers: X-FortunCred-Signature: sha256=<hex> e X-FortunCred-Timestamp: <epoch>. Recuse entregas fora da janela de tolerância (anti-replay), monte a mesma string assinada (timestamp.corpo) e compare em tempo constante:

// Node.js
const crypto = require('crypto');

function assinaturaOk(corpoCru, header, timestampHeader, secret, toleranciaSeg = 300) {
  if (typeof header !== 'string' || typeof timestampHeader !== 'string') return false;

  // 1) anti-replay: recusa entregas fora da janela de tolerância
  const agora = Math.floor(Date.now() / 1000);
  const ts = Number.parseInt(timestampHeader, 10);
  if (!Number.isFinite(ts) || Math.abs(agora - ts) > toleranciaSeg) return false;

  // 2) o timestamp entra no que é assinado (mesma ordem do servidor)
  const esperado = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${ts}.`).update(corpoCru)
    .digest('hex');

  // 3) compara o TAMANHO antes do timingSafeEqual (evita RangeError)
  const a = Buffer.from(header), b = Buffer.from(esperado);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

O secret de assinatura é entregue com a sua credencial. Se precisar rotacioná-lo, fale com o suporte.

OAuth sob demanda (enterprise)

Para integrações que exijam padrão bancário por contrato/compliance, a FortunCred pode disponibilizar o fluxo OAuth2 client_credentials (client_id + client_secret → token de acesso temporário), sem remover a API Key. É uma opção sob demanda — a maioria dos parceiros usa a API Key pela simplicidade. Fale com o consultor que te atende na FortunCred se este for o seu caso.

Reportar uma vulnerabilidade

Encontrou uma falha de segurança? Escreva para integracao@pcapitalassessoria.com.br com os detalhes e, se aplicável, o request_id da resposta. Pedimos que você não divulgue publicamente até a correção. Nunca inclua na mensagem sua API Key nem dados sensíveis de clientes (CPF, renda).