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>'

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

Gestão de chaves

Sub-keys

Onde usar sub-keys

Criar uma sub-key

Remover uma sub-key

Chave secreta

​Gestão de chaves

​Sub-keys

​Onde usar sub-keys

​Criar uma sub-key

​Remover uma sub-key

​Chave secreta

Gestão de chaves

Sub-keys

Onde usar sub-keys

Criar uma sub-key

Remover uma sub-key

Chave secreta