Autenticação

A autenticação da Malvo segue duas superfícies paralelas, projetadas para separar o que é server-side (com acesso total aos dados) do que pode chegar ao browser do usuário (escopo restrito ao widget). Toda a API vive sob um único host: https://api.malvo.io. A cadeia completa parte das suas credenciais de aplicação e termina em um token efêmero entregue ao cliente:

clientId + clientSecret        (do Dashboard, server-side, NUNCA enviados ao browser)
        │
        ▼  POST /auth
   apiKey  (header X-API-KEY)            ← vive 2 horas, acesso server-side total
        │
        ▼  POST /connect_token
   connectToken (accessToken)            ← vive 30 minutos, escopo do widget
        │
        ▼  entregue ao cliente
   Connect Widget                        ← usuário autentica no banco dele
        │
        ▼
   Item + dados de produto

As duas superfícies

A Malvo expõe credenciais com escopos deliberadamente diferentes. Entender qual usar em cada lugar é o ponto central da segurança da integração.

Superfície	Credencial	Header	TTL	Pode
Server-side	`apiKey`	`X-API-KEY`	2 horas	Criar connect tokens, ler todos os dados de produto, configurar webhooks, criar/atualizar/excluir items, listar connectors
Client-side	`connectToken`	(usado pelo widget)	30 minutos	Apenas dirigir o Connect Widget e ler o próprio item que ele criou/atualiza

O connectToken é escopado ao widget. Qualquer tentativa de ler dados detalhados de produto (contas, transações, cartões etc.) usando um connect token retorna 403 Forbidden. Dados de produto só são lidos server-side com X-API-KEY.

Cada token é consumido de forma atômica na primeira criação/atualização e fica vinculado a um único itemId. Um retry idêntico retoma somente esse Item (e reutiliza a autorização já persistida); ele nunca cria um segundo Item. Trocar o Connector retorna 409. Durante a continuação OAuth, polling e MFA também só conseguem acessar o Item vinculado.

Passo a passo

Obtenha clientId e clientSecret

As credenciais da aplicação são emitidas no Dashboard, uma por Application. O clientSecret é server-side e nunca deve chegar ao browser.

Troque por um apiKey via POST /auth

Envie clientId e clientSecret para POST /auth. A resposta traz um apiKey com TTL de exatamente 2 horas, usado no header X-API-KEY de todas as chamadas server-side.

Mint de um connectToken via POST /connect_token

Com o apiKey no header, chame POST /connect_token para gerar um token de 30 minutos. O corpo pode ser {} (cria um novo item) ou conter itemId (modo de atualização de um item existente).

Entregue o connectToken ao cliente

O accessToken retornado é o único valor de autenticação que pode chegar ao browser. Ele dirige o Connect Widget enquanto o usuário autentica no banco dele.

POST /auth — credenciais para apiKey

Sem header de autenticação. Limite: 360 requisições/min por IP.

curl -X POST https://api.malvo.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "b6e3a4c2-1234-4d5e-9f00-abcdefabcdef",
    "clientSecret": "s3cr3t-opaque-string"
  }'

const res = await fetch("https://api.malvo.io/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "b6e3a4c2-1234-4d5e-9f00-abcdefabcdef",
    clientSecret: "s3cr3t-opaque-string",
  }),
});

const { apiKey } = await res.json();

Resposta 200:

{ "apiKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

O apiKey é uma string opaca (JWT-like) com TTL de exatamente 2 horas a partir da emissão. Emitir um novo apiKey não invalida os anteriores — a validação é stateless e só observa a expiração.

HTTP	`codeDescription`	Significado
401	`CLIENT_KEYS_UNAUTHORIZED`	`clientId`/`clientSecret` incorretos
401	`CLIENT_DISABLED`	Credenciais corretas, mas a Application foi desativada. Repetir nunca resolve — verifique o Dashboard
500	`INTERNAL_SERVER_ERROR`	Falha de servidor — tente novamente com backoff

Cache e refresh do apiKey

O apiKey deve ser cacheado e reutilizado entre chamadas — não chame POST /auth a cada requisição. Renove proativamente:

Antecipadamente, por volta de 1h50m após a emissão (margem antes do TTL de 2h).
Reativamente, no primeiro 401 recebido em um endpoint de dados (apiKey expirou): refaça POST /auth uma vez e repita a chamada original.

POST /connect_token — apiKey para connectToken

Requer header X-API-KEY: <apiKey>. Todos os campos do corpo são opcionais — {} é válido e retorna um token para criar um novo item.

curl -X POST https://api.malvo.io/connect_token \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "options": {
      "clientUserId": "usuario-42",
      "webhookUrl": "https://suaapp.com.br/webhooks/malvo",
      "oauthRedirectUri": "https://suaapp.com.br/oauth/callback",
      "avoidDuplicates": true,
      "products": ["ACCOUNTS", "TRANSACTIONS"]
    }
  }'

const res = await fetch("https://api.malvo.io/connect_token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": apiKey,
  },
  body: JSON.stringify({
    options: {
      clientUserId: "usuario-42",
      webhookUrl: "https://suaapp.com.br/webhooks/malvo",
      oauthRedirectUri: "https://suaapp.com.br/oauth/callback",
      avoidDuplicates: true,
      products: ["ACCOUNTS", "TRANSACTIONS"],
    },
  }),
});

const { accessToken } = await res.json();

Resposta 200:

{ "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOi..." }

O accessToken tem TTL de exatamente 30 minutos. Gere um token novo toda vez que o usuário abrir o widget. Para atualizar um item existente (re-autenticação, MFA, renovação de consentimento), inclua itemId no corpo — o widget entra em modo de atualização.

HTTP	`codeDescription`	Significado
403	— (`"Missing or invalid authorization token"`)	`X-API-KEY` ausente, malformado ou expirado
404	`ITEM_NOT_FOUND`	O `itemId` passado para atualização não existe ou foi excluído
500	`INTERNAL_SERVER_ERROR`	Tente novamente com backoff

O detalhe 403-vs-401 no /connect_token

Atenção à semântica 403, não 401: falha de autenticação no POST /connect_token (apiKey ausente, malformado ou expirado) retorna 403 Forbidden, e não 401. Trate esse 403 como “renove o apiKey via POST /auth e repita” — não como um problema de permissão. Em endpoints de dados, ao contrário, um apiKey inválido/expirado retorna 401.

Resumo do que cada código significa em cada superfície:

401 em endpoint de dados → apiKey expirou; refaça POST /auth e repita.
403 em POST /connect_token → apiKey ausente/expirado; refaça POST /auth e repita.
403 em endpoint de dados → você usou um connectToken para ler dados de produto; use X-API-KEY server-side.

Segurança

clientId, clientSecret e apiKey nunca devem chegar ao browser. O único valor de autenticação que o cliente vê é o connectToken de 30 minutos. Mantenha o segredo e o apiKey estritamente server-side.

Nunca exponha o clientSecret no front-end, em apps mobile ou em repositórios públicos. Faça o POST /auth sempre a partir do seu backend.
O connectToken é de curta duração e de escopo mínimo por design: mesmo que vaze, só dirige o widget e lê o próprio item.
Os webhooks são a fonte autoritativa do estado assíncrono das conexões; o onSuccess do widget é best-effort (o usuário pode fechar o widget no meio do fluxo).
Validação rápida de um apiKey fresco: GET /connectors com X-API-KEY deve retornar a lista de connectors.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Autenticação

As duas superfícies

Passo a passo

POST /auth — credenciais para apiKey

Cache e refresh do apiKey

POST /connect_token — apiKey para connectToken

O detalhe 403-vs-401 no /connect_token

Segurança

​As duas superfícies

​Passo a passo

​POST /auth — credenciais para apiKey

​Cache e refresh do apiKey

​POST /connect_token — apiKey para connectToken

​O detalhe 403-vs-401 no /connect_token

​Segurança

As duas superfícies

Passo a passo

POST /auth — credenciais para apiKey

Cache e refresh do apiKey

POST /connect_token — apiKey para connectToken

O detalhe 403-vs-401 no /connect_token

Segurança