> ## 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.

# Autenticação

> Gere no seu backend uma sub-key com escopo tokens e validade curta para cada sessão de checkout e use essa chave no SDK de Tokenização, sem expor a chave secreta no front-end.

O SDK de Tokenização roda no navegador. Por isso, a `apiKey` informada ao SDK fica visível para qualquer pessoa que abrir a página do checkout, seja no HTML, no bundle JavaScript ou nas requisições de rede.

Para o SDK, use sempre uma [sub-key](https://docs.malga.io/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side.md) gerada no seu backend, só com o escopo `tokens` e com validade curta. A chave secreta da sua conta fica só no seu servidor.

> [!WARNING]
>
> Nunca use a chave secreta da sua conta (a chave do Dashboard) na `apiKey` do SDK. Ela dá acesso a toda a API.

## Como funciona

```mermaid theme={null}
sequenceDiagram
  participant N as "Navegador (checkout + SDK)"
  participant B as "Seu backend"
  participant M as "API Malga"
  N ->> B: Cliente abre a tela de pagamento<br/>e pede uma sub-key
  B ->> M: POST /v1/auth com a chave secreta<br/>scope tokens, expires 900
  M -->> B: publicKey (sub-key)
  B -->> N: Só o publicKey e o clientId
  N ->> N: Cria MalgaTokenization<br/>com apiKey = publicKey
  N ->> M: tokenize() com a sub-key
  M -->> N: tokenId
  N ->> B: Envia o tokenId
  B ->> M: POST /v1/charges com a chave secreta
  M -->> B: Cobrança criada
```

* A chave secreta só aparece nas chamadas entre o seu backend e a Malga.
* O navegador recebe apenas a sub-key, com escopo `tokens` e válida por 15 minutos.
* Cada abertura do checkout gera uma sub-key nova.

## 1. Crie a sub-key no backend

Crie no seu backend uma rota que o checkout chama ao abrir a tela de pagamento. Essa rota deve:

1. Chamar `POST /v1/auth` com o `X-Client-Id` e a chave secreta da sua conta, pedindo `{"scope": ["tokens"], "expires": 900}`.
2. Devolver ao front-end só o `publicKey` e o `clientId` da resposta, nunca a chave secreta.

Guarde a chave secreta em variáveis de ambiente ou em um cofre de segredos do servidor. Use `https://sandbox-api.malga.io` com as credenciais de Sandbox e `https://api.malga.io` com as de Produção.

Requisição:

```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}
{
  "publicKey": "YOUR_PUBLIC_KEY",
  "clientId": "YOUR_CLIENT_ID",
  "scope": ["tokens"],
  "expires": 900,
  "createdAt": "2026-09-30T14:00:00.000Z"
}
```

> [!NOTE]
>
> O campo `expires` é em **segundos**. `900` equivale a 15 minutos. Veja a tabela de prazos em [Criar sub-key](https://docs.malga.io/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side.md#tempo-de-validade-expires).

## 2. Crie a instância do SDK com a sub-key

No front-end, busque a sub-key na rota do seu backend (no exemplo, `/checkout/malga-key`) e só depois crie a instância. Não crie a instância no carregamento do módulo com uma chave fixa.

```typescript checkout.ts theme={null}
import { MalgaTokenization } from '@malga/tokenization'

async function createMalgaTokenization() {
  const response = await fetch('/checkout/malga-key', { method: 'POST' })
  const { publicKey, clientId } = await response.json()

  return new MalgaTokenization({
    apiKey: publicKey,
    clientId,
    options: {
      sandbox: true,
      config: {
        fields: {
          cardNumber: { container: 'card-number' },
          cardHolderName: { container: 'card-holder-name' },
          cardCvv: { container: 'card-cvv' },
          cardExpirationDate: { container: 'card-expiration-date' },
        },
      },
    },
  })
}

const malgaTokenization = await createMalgaTokenization()

async function handleSubmit(event: SubmitEvent) {
  event.preventDefault()

  const { tokenId, error } = await malgaTokenization.tokenize()
  // Envie o tokenId para o seu backend
}
```

Em React, Vue ou Angular, busque a sub-key no mesmo ponto em que você cria a instância (por exemplo, no `useEffect`, no `onMounted` ou no `ngOnInit`) e chame [`destroy()`](https://docs.malga.io/sdks/tokenization/v2/events#destroy) na desmontagem.

## Quando a sub-key expira

A instância usa a `apiKey` informada na criação. Depois do prazo de `expires`, a API recusa a tokenização com essa sub-key.

* Crie a sub-key quando o cliente abrir a tela de pagamento, não no início da navegação na loja.
* Se a sua jornada de pagamento costuma passar de 15 minutos, use um prazo um pouco maior, como `3600` (1 hora), em vez de uma chave sem expiração.
* Para trocar a sub-key, chame `destroy()` na instância atual, busque uma sub-key nova no backend e crie outra instância. Os dados digitados nos campos não são mantidos, então peça ao cliente para digitar o cartão de novo.

## Boas práticas

> [accordion] Use só o escopo tokens
>
> O SDK de Tokenização só precisa do escopo `tokens`. Não use no front-end escopos que alteram a sua conta ou movimentam dinheiro, como `charges`, `purchases`, `webhooks`, `merchants` e `auth`.

> [accordion] Use validade curta e uma sub-key por sessão de checkout
>
> Prefira `expires: 900` e gere uma sub-key nova a cada sessão de checkout. Não use `expires: 0` no front-end: uma sub-key sem expiração continua válida por tempo indeterminado para quem tiver acesso a ela.

> [accordion] Não deixe a chave fixa no HTML ou no bundle
>
> Uma chave escrita no HTML, em um arquivo de configuração do front-end ou em variáveis de build (como as que vão para o bundle JavaScript) é a mesma para todos os visitantes e não muda entre as sessões. Busque a sub-key no backend em tempo de execução.

> [accordion] Proteja a rota que gera a sub-key
>
> A rota do seu backend que cria sub-keys fica acessível pelo navegador. Gere a sub-key só quando houver uma sessão de compra válida no seu sistema (por exemplo, um carrinho ou pedido em andamento) e aplique limite de requisições nessa rota.

> [accordion] Use chaves diferentes para Sandbox e Produção
>
> As credenciais de um ambiente não funcionam no outro. Gere as sub-keys de Sandbox em `https://sandbox-api.malga.io`, com as credenciais de Sandbox, e as de Produção em `https://api.malga.io`, com as credenciais de Produção. Use `options.sandbox: true` só com sub-keys de Sandbox e `false` em Produção.

> [accordion] Revise e remova chaves que você não usa
>
> Revise periodicamente as sub-keys e chaves da sua conta. [Remova](https://docs.malga.io/api-reference/client-token/remover-sub-key.md) sub-keys que não estão mais em uso, principalmente as criadas sem expiração.

> [card] [Criar sub-key](https://docs.malga.io/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side.md)
>
> Veja escopos, prazos e erros da criação de sub-keys.

> [card] [Configuração](https://docs.malga.io/sdks/tokenization/v2/configuration.md)
>
> Configure os campos e as opções do SDK.


## Related topics

- [Autenticação](https://docs.malga.io/api-reference/authentication.md)
- [Principais erros na autenticação 3DS da Malga](https://docs.malga.io/documentations/3ds2-malga/3ds-malga/principais-erros.md)
- [Sobre as APIs da Malga](https://docs.malga.io/api-reference/about-apis.md)
- [Começando em 3DS2 Malga](https://docs.malga.io/documentations/3ds2-malga/intro.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.