Autentique-se com a Malga

Os serviços da Malga são protegidos através de chaves de acesso. Você pode gerenciar suas chaves de acesso através do seu Dashboard. É importante armazenar suas chaves de maneira privada e segura, uma vez que elas possuem privilégios de alteração na sua conta. Não compartilhe suas chaves, não deixe elas fixadas no seu código e nem armazene elas no seu servidor de controle de versão. Recomendamos utilizar variáveis de ambiente secretas para deixar a chave disponível para sua aplicação.

A Autenticação para todas as chamadas da API é feita através de headers HTTP, sendo necessário informar seu identificador de cliente na Malga e a chave secreta de acesso.

  curl --location --request GET 'https://api.malga.io/v1/' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>'

Ambientes

A Malga disponibiliza dois ambientes, cada um com URL base e credenciais próprias:

Ambiente	URL base	Uso
Sandbox	`https://sandbox-api.malga.io`	Testes de integração, sem valores reais
Produção	`https://api.malga.io`	Processamento de pagamentos reais

Os exemplos desta documentação usam a URL de produção. Para testar, substitua https://api.malga.io por https://sandbox-api.malga.io e use o X-Client-Id e a X-Api-Key de sandbox.

Cobranças criadas em sandbox-api.malga.io aparecem apenas no ambiente de testes (sandbox) do Dashboard, e não no ambiente de produção. As credenciais de um ambiente não funcionam no outro.

Veja os cenários disponíveis para simulação no Guia de teste.

Gestão de chaves

Sua conta tem dois tipos de chave:

Tipo	Onde obter	Acesso	Validade
Chave secreta (chave principal)	No Dashboard	Toda a API	Até ser revogada
Sub-key	Pela API (`POST /v1/auth`), usando a chave secreta	Só os escopos escolhidos na criação	Definida por você no campo `expires`

Sub-keys

Sub-keys são chaves derivadas da chave secreta da sua conta, com escopo e tempo de validade limitados. Você gerencia as sub-keys integralmente pela API, sem abrir chamado com a Malga:

Criação: com escopos (scope) e tempo de validade em segundos (expires). Veja Criar sub-key.
Remoção: antes do fim da validade, para fazer uma rotação manual. Veja Remover sub-key.

Uma sub-key é usada como a chave secreta, no header X-Api-Key, mas só acessa os escopos dela e deixa de funcionar quando expira ou é removida.

Onde usar sub-keys

Aplicações back-end: dê a cada serviço ou time uma sub-key só com os escopos de que ele precisa, em vez de compartilhar a chave secreta. Por exemplo, uma ferramenta interna que só estorna cobranças recebe uma sub-key com o escopo charges/*/void.
Aplicações client-side: no navegador ou em aplicativos, a sub-key fica exposta. Use sub-keys de curta duração (por exemplo, 900 segundos) e, de preferência, só com o escopo tokens, para tokenizar cartões. Crie uma sub-key nova a cada sessão de compra.

Uso	Escopo	Validade sugerida
Tokenização de cartões no checkout do navegador	`tokens`	`900` (15 minutos)
Aplicativo que tokeniza e lista cartões salvos	`tokens`, `cards`	`3600` (1 hora)
Ferramenta interna de atendimento que só estorna cobranças	`charges/*/void`	`86400` (24 horas)
Ferramenta de BI que consulta a Analytics API	`graphql`	Conforme a política de rotação da sua empresa

Criar uma sub-key

Faça a chamada no seu servidor, com a chave secreta:

curl --location --request POST 'https://api.malga.io/v1/auth' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "scope": ["tokens"],
    "expires": 900
  }'

Resposta 201:

{
  "clientId": "YOUR_CLIENT_ID",
  "publicKey": "YOUR_PUBLIC_KEY",
  "scope": ["tokens"],
  "expires": 900,
  "createdAt": "2026-09-30T14:00:00.000Z"
}

Use o publicKey no header X-Api-Key:

curl --location --request POST 'https://api.malga.io/v1/tokens' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_PUBLIC_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "cardHolderName": "JOSE DAS NEVES",
    "cardNumber": "4019598346009339",
    "cardCvv": "123",
    "cardExpirationDate": "12/2026"
  }'

Remover uma sub-key

A sub-key expira sozinha quando termina o tempo definido em expires. Se você quiser fazer uma rotação manual ou bloquear uma sub-key exposta, remova a sub-key antes do prazo, informando o publicKey dela na rota:

curl --location --request DELETE 'https://api.malga.io/v1/auth/YOUR_PUBLIC_KEY' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY'

A resposta de sucesso é 200, sem corpo. Depois disso, as chamadas com a sub-key removida são recusadas com 403.

Chave secreta

A Malga oferece suporte a duas chaves secretas ativas ao mesmo tempo. Para trocar a chave secreta, gere uma nova chave e mantenha a anterior ativa durante a transição. Assim, você migra a integração sem interromper as chamadas à API. Depois da migração, revogue a chave anterior. Hoje, a revogação da chave secreta é feita pelo suporte da Malga: abra um chamado pedindo a revogação. Não envie a chave secreta no chamado. Chamados urgentes, como o vazamento de uma chave, têm SLA contratual de resolução em até 2 horas, 24/7.

Comece na Malga

Conexões

Guias

Serviços adicionais

Autentique-se com a Malga

Ambientes

Gestão de chaves

Sub-keys

Onde usar sub-keys

Criar uma sub-key

Remover uma sub-key

Chave secreta

​Ambientes

​Gestão de chaves

​Sub-keys

​Onde usar sub-keys

​Criar uma sub-key

​Remover uma sub-key

​Chave secreta

Ambientes

Gestão de chaves

Sub-keys

Onde usar sub-keys

Criar uma sub-key

Remover uma sub-key

Chave secreta