> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.
# 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.
```bash theme={null}
curl --location --request GET 'https://api.malga.io/v1/' \
--header 'X-Client-Id: ' \
--header 'X-Api-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](/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side).
* **Remoção:** antes do fim da validade, para fazer uma rotação manual. Veja [Remover sub-key](/api-reference/client-token/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](/analytics/authentication/authentication) | `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:
```bash theme={null}
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`:
```json theme={null}
{
"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`:
```bash theme={null}
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:
```bash theme={null}
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.
## Related topics
- [Primeiros passos](/documentations/welcome/primeiros-passos.md)
- [Autenticação](/api-reference/authentication.md)
- [Tratamento de erros na integração](/documentations/welcome/errors.md)
- [Realizar nova cobrança](/api-reference/charges/realizar-nova-cobranca.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.