A segurança da integração com a Malvo se apoia em quatro pilares: credenciais de escopo mínimo, transporte cifrado, webhooks autenticados por origem e conformidade com LGPD / Open Finance. Toda a API vive sob um único host — https://api.malvo.io — e o Dashboard fica em https://malvo.io/dashboard. Não há iniciação de pagamentos (ITP): a plataforma é exclusivamente agregação e enriquecimento de dados, o que reduz a superfície de risco da integração.

​
Credenciais e escopos

A Malvo separa deliberadamente o que é server-side (acesso total) do que pode chegar ao browser (escopo restrito). Usar a credencial certa em cada lugar é o ponto central da segurança.
clientId, clientSecret e apiKey nunca podem chegar ao browser, a apps mobile ou a repositórios públicos. O único valor de autenticação que o cliente vê é o connectToken de 30 minutos. Faça o POST /auth sempre a partir do seu backend.
O connectToken é de escopo restrito por design: qualquer tentativa de ler dados detalhados de produto (contas, transações, cartões etc.) com um connect token retorna 403 Forbidden. Mesmo que ele vaze, só dirige o widget e lê o item que criou.

​
Rotação do clientSecret

1

Gere um novo secret no Dashboard

No Dashboard, abra a Application e gere um novo clientSecret.
2

Atualize o secret manager

Substitua o valor antigo no seu cofre / secret manager e faça o deploy do backend.
3

Revogue o secret antigo

Após confirmar que o POST /auth funciona com o novo valor, revogue o anterior no Dashboard.
O apiKey é stateless e expira sozinho em 2 horas — emitir um novo não invalida os anteriores. Cacheie-o no servidor e renove proativamente (por volta de 1h50m) ou no primeiro 401. Veja Autenticação.

​
Transporte

Armazene clientSecret e apiKey em um secret manager / cofre (por exemplo, AWS Secrets Manager, GCP Secret Manager, Vault), nunca em variáveis de ambiente commitadas, bundles de front-end ou logs. Trate-os como credenciais de produção.

​
Webhooks

A Malvo não assina os payloads com HMAC. A autenticidade de uma entrega é garantida por dois mecanismos combinados:
  • Headers customizados por webhook — um mapa headers (nome → valor) enviado verbatim em toda entrega, onde você coloca o seu segredo compartilhado. É write-only: aceito no POST /webhooks / PATCH /webhooks/{id}, mas nunca retornado em GET nem exibido no Dashboard. A rotação é feita reescrevendo o mapa via PATCH.
  • IP allowlisting — todas as entregas saem de um único IP de egress estático. Adicione-o à allowlist do seu firewall/WAF.
O IP de egress estático dos webhooks está disponível no seu Dashboard, na seção Webhooks. Use sempre o valor publicado lá — não codifique um IP a partir de qualquer outra fonte.
Valide toda entrega pela origem (IP + header de auth) e pela idempotência (eventId): a Malvo reutiliza o mesmo eventId em todas as reentregas e em todos os endpoints assinados, então persista-o e trate duplicatas como no-op antes de aplicar qualquer efeito. Detalhes completos do modelo e do handler de exemplo em Segurança de Webhooks.

​
LGPD & Open Finance

No Open Finance Brasil, o consentimento é a base legal para a leitura de dados. A LGPD garante ao titular o direito de revogar esse consentimento a qualquer momento.
Conformidade obrigatória. Sua integração deve sempre oferecer ao usuário uma ação de “Desconectar banco / Revogar consentimento”, disponível a qualquer momento. Essa ação chama DELETE /items/{id}.Ao excluir o Item: GET /items/{id} passa a retornar 404 e todos os dados vinculados (contas, transações, etc.) tornam-se permanentemente inacessíveis pela API. Internamente, a Malvo também revoga o consentimento correspondente na rede.
O usuário também pode revogar o registro de consentimento pelo lado do banco, no app dele, independentemente da sua integração. Quando isso ocorre, os endpoints de dados passam a retornar vazio e o Item vai para OUTDATED. Veja o ciclo de vida e a renovação em Consents.

​
Boas práticas

  • Least-privilege de papéis. Conceda a cada membro do time apenas o acesso necessário no Dashboard; mantenha o conjunto de administradores/owners enxuto. Veja Membros & papéis.
  • Logs e auditoria. Registre as ações sensíveis da sua integração (criação/exclusão de items, rotações de secret) e mantenha trilhas de auditoria.
  • Rastreabilidade. Toda resposta da API traz um identificador de requisição no header x-request-id e no campo requestId do corpo. Logue-o — ele é o que permite ao suporte investigar uma chamada específica.
  • Reporte com itemId. Em qualquer problema de conexão, o itemId é obrigatório para análise; inclua-o sempre junto do requestId.

​
Checklist de segurança

1

clientSecret só no servidor

clientId / clientSecret nunca chegam ao browser; o POST /auth roda apenas no backend.
2

Segredos no cofre

clientSecret e apiKey ficam em secret manager/cofre — fora de bundles, logs e do controle de versão.
3

connectToken no client

Só o connectToken de 30 min é entregue ao browser; ele não lê dados de produto (403).
4

TLS 1.2+

Todas as chamadas usam HTTPS com TLS 1.2+ e Content-Type: application/json.
5

Webhooks autenticados

Header de auth customizado configurado e o IP de egress (do Dashboard) na allowlist do WAF.
6

Idempotência de webhooks

O eventId é persistido e duplicatas são tratadas como no-op.
7

"Desconectar banco" sempre disponível

A ação que chama DELETE /items/{id} está exposta ao usuário a qualquer momento (LGPD / Open Finance).
8

Least-privilege de papéis

Acessos do time no Dashboard seguem o menor privilégio necessário.
9

Rastreio por requestId

x-request-id / requestId são logados em todas as chamadas, junto do itemId quando houver.

​
Próximos passos

Autenticação

A cadeia clientId → apiKey → connectToken em detalhe.

Consents

Ciclo de vida do consentimento, revogação e renovação no mesmo Item.

Segurança de Webhooks

Headers write-only, IP allowlist e validação de origem.

Membros & papéis

Least-privilege de acesso ao Dashboard.