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

Toda entrega leva Malvo-Signature (HMAC-SHA256 do corpo cru). Verifique o header com o signing secret da aplicação antes de qualquer efeito — vetor de teste e handler em Segurança de Webhooks. Headers customizados e IP allowlisting continuam como defesa em profundidade:
  • Headers customizados por webhook — mapa enviado verbatim em toda entrega. A API pública não devolve o mapa em GET; owners/admins editam no Dashboard. O signing secret HMAC é outro material (página Webhooks → Revelar).
  • IP allowlisting — as entregas saem de um IP de egress estático. O valor ainda não aparece na página Webhooks; confirme com o suporte da Malvo.
Valide nesta ordem: HMAC → IP (se você filtra) → header customizado (se houver) → JSON → eventId. A Malvo reutiliza o mesmo eventId em reentregas e entre endpoints inscritos.

​
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

Malvo-Signature verificado no corpo cru; headers customizados e IP de egress como defesa extra.
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

HMAC Malvo-Signature, headers customizados e allowlist de IP.

Membros & papéis

Least-privilege de acesso ao Dashboard.