Criar sub-key

curl --request POST \
  --url https://api.malga.io/v1/auth \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Client-Id: <api-key>' \
  --data '
{
  "scope": [
    "tokens"
  ],
  "expires": 3600
}
'

{
  "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
  "publicKey": "YOUR_PUBLIC_KEY",
  "scope": [
    "tokens"
  ],
  "expires": 3600,
  "createdAt": "2026-09-30T14:00:00.000Z"
}

{
  "statusCode": 422,
  "message": "payments is not a valid scope.",
  "error": "Unprocessable Entity"
}

{
  "error": {
    "type": "api_error",
    "code": 123,
    "declinedCode": "<string>",
    "key": "<string>",
    "businessCode": "<string>",
    "message": "<string>",
    "details": "<array>"
  }
}

POST

auth

curl --request POST \
  --url https://api.malga.io/v1/auth \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Client-Id: <api-key>' \
  --data '
{
  "scope": [
    "tokens"
  ],
  "expires": 3600
}
'

{
  "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
  "publicKey": "YOUR_PUBLIC_KEY",
  "scope": [
    "tokens"
  ],
  "expires": 3600,
  "createdAt": "2026-09-30T14:00:00.000Z"
}

{
  "statusCode": 422,
  "message": "payments is not a valid scope.",
  "error": "Unprocessable Entity"
}

{
  "error": {
    "type": "api_error",
    "code": 123,
    "declinedCode": "<string>",
    "key": "<string>",
    "businessCode": "<string>",
    "message": "<string>",
    "details": "<array>"
  }
}

A chave secreta da sua conta dá acesso a toda a API. Em vez de distribuí-la entre as suas aplicações, crie sub-keys: chaves derivadas da chave secreta, que só acessam os escopos que você escolher e deixam de funcionar quando expiram. Você gerencia as sub-keys pela API, sem abrir chamado com a Malga: crie quantas precisar, cada uma com os próprios escopos e validade, e remova as que não usa mais.

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. Por exemplo, uma ferramenta interna de atendimento que só estorna cobranças recebe uma sub-key com o escopo charges/*/void.

Aplicações client-side

No navegador ou em aplicativos, use sub-keys de curta duração e, de preferência, só com o escopo tokens, para tokenizar cartões. Crie uma sub-key nova a cada sessão de compra.

Como funciona

Crie a sub-key no seu servidor

Chame POST /v1/auth com o X-Client-Id e a chave secreta da sua conta no X-Api-Key. A chave secreta precisa ter o escopo * ou auth.

Entregue a sub-key à aplicação

Repasse o publicKey da resposta para o serviço, o navegador ou o aplicativo que vai usá-lo. A chave secreta continua só no seu servidor.

Use a sub-key nas chamadas

Envie o publicKey no header X-Api-Key, junto com o mesmo X-Client-Id da sua conta.

Exemplo de criação

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": 3600
  }'

Resposta 201:

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

Com a sub-key criada, o front-end pode tokenizar um cartão:

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

Tempo de validade (`expires`)

O campo expires é obrigatório e define por quantos segundos a sub-key vale, contados a partir da criação. Depois desse prazo, as chamadas com a sub-key são recusadas com 403. Para invalidar uma sub-key antes do prazo, remova a sub-key.

`expires`	Validade	Quando usar
`900`	15 minutos	Uma tela de pagamento: crie a sub-key quando o cliente abrir o checkout
`3600`	1 hora	Jornadas de compra mais longas
`86400`	24 horas	Ferramentas internas usadas ao longo do dia
`2592000`	30 dias	Integrações em que a sub-key fica configurada por mais tempo
`0`	Sem expiração	Aplicações back-end em que a sub-key não fica exposta, como a Analytics API em um servidor. Troque a sub-key de tempos em tempos

Para sub-keys usadas no navegador ou em aplicativos, prefira um prazo curto e crie uma sub-key nova a cada sessão de compra. Evite 0: uma sub-key sem expiração continua válida se for copiada do front-end.

Escopos (`scope`)

O campo scope é obrigatório e recebe uma lista com um ou mais escopos. Cada escopo libera todos os métodos HTTP no recurso /v1/<escopo> e em todos os caminhos abaixo dele. Por exemplo, o escopo charges libera GET /v1/charges/{id}, POST /v1/charges, POST /v1/charges/{id}/capture e POST /v1/charges/{id}/void. Para liberar só uma operação, use os escopos com * no lugar do id, como charges/*/void.

Escopo	O que libera
`tokens`	Tokenização de cartões (`/v1/tokens`)
`cards`	Cartões salvos (`/v1/cards`)
`customers`	Clientes e os cartões de cada cliente (`/v1/customers`)
`charges`	Cobranças e todas as operações sobre elas, inclusive captura e estorno (`/v1/charges`)
`charges/*/capture`	Somente a captura de cobranças pré-autorizadas
`charges/*/void`	Somente o estorno de cobranças
`sessions`	Sessões de pagamento (`/v1/sessions`)
`purchases`	Vendas e todas as operações sobre elas (`/v1/purchases`)
`purchases//capture`, `purchases//void`, `purchases/*/history`	Somente a captura, o cancelamento ou estorno, ou o histórico de uma Venda
`subscriptions`	Motor de Assinaturas (`/v1/subscriptions`)
`flows`	Fluxos inteligentes (`/v1/flows`)
`sellers`	Sellers do Split de pagamentos (`/v1/sellers`)
`providers`	Provedores (`/v1/providers`)
`merchants`	Merchants (`/v1/merchants`)
`vendors`	Vendors (`/v1/vendors`)
`webhooks`	Configuração de webhooks (`/v1/webhooks`)
`graphql`	Analytics API (`POST /v1/graphql`)
`auth`	Criação e remoção de sub-keys (`/v1/auth`)

Um escopo fora da lista retorna 422, e uma chamada a um recurso fora dos escopos da sub-key retorna 403.

Libere só o que cada aplicação precisa. No checkout, tokens costuma ser suficiente. Não use no client-side escopos que alteram a sua conta ou movimentam dinheiro, como charges, purchases, webhooks, merchants e auth: com eles, qualquer pessoa que copiar a sub-key do navegador pode, por exemplo, estornar cobranças ou criar e remover chaves. Reserve o escopo auth para o servidor que gerencia as suas sub-keys.

Exemplos de escopo

{
  "scope": ["tokens"],
  "expires": 900
}

{
  "scope": ["tokens", "cards"],
  "expires": 900
}

{
  "scope": ["charges/*/void"],
  "expires": 86400
}

{
  "scope": ["graphql"],
  "expires": 0
}

Erros comuns

HTTP code	Quando acontece	O que fazer
`400`	O corpo tem campos fora do contrato, `scope` não é uma lista ou `expires` é negativo	Envie só `scope` (lista) e `expires` (número maior ou igual a `0`)
`403`	Na criação: a chave secreta não existe, não pertence ao `X-Client-Id` ou não tem o escopo `*` ou `auth`. No uso: a sub-key expirou ou foi removida, o `X-Client-Id` é de outra conta ou o recurso está fora dos escopos	Confira as chaves e os escopos. Se a sub-key expirou ou foi removida, crie uma nova
`422`	Um ou mais escopos não são válidos	Use os escopos da tabela acima

Exemplo de resposta 422:

{
  "statusCode": 422,
  "message": "payments is not a valid scope.",
  "error": "Unprocessable Entity"
}

Veja também Gestão de chaves.

Authorizations

X-Client-Id

string

header

required

X-Api-Key

string

header

required

Body

application/json

Escopos e tempo de validade da sub-key

scope

enum<string>[]

required

Lista de escopos que a sub-key pode acessar. Cada escopo libera todos os métodos HTTP no recurso /v1/<escopo> e nos caminhos abaixo dele. Por exemplo, charges libera /v1/charges, /v1/charges/{id}, /v1/charges/{id}/capture e /v1/charges/{id}/void. Use graphql para a Analytics API (POST /v1/graphql).

Um escopo fora da lista retorna 422.

Minimum array length: 1

Available options:

tokens,

cards,

customers,

charges,

charges/*/capture,

charges/*/void,

sessions,

purchases,

purchases/*/capture,

purchases/*/void,

purchases/*/history,

subscriptions,

flows,

sellers,

providers,

merchants,

vendors,

webhooks,

graphql,

auth

Example:

["tokens"]

expires

number

required

Tempo de validade da chave, em segundos, contado a partir da criação. Use 0 para criar uma chave sem expiração. Exemplos: 900 (15 minutos), 3600 (1 hora), 86400 (24 horas).

Required range: x >= 0

Example:

3600

Response

Created

publicKey

string<uuid>

Sub-key criada. Envie esse valor no header X-Api-Key, junto com o X-Client-Id da sua conta. Use o mesmo valor como id para remover a sub-key

clientId

string<uuid>

Identificador do cliente na Malga. É o mesmo X-Client-Id da chave secreta usada na criação

scope

string[]

Escopos da chave, iguais aos enviados na requisição

expires

number

Tempo de validade enviado na requisição, em segundos. 0 indica uma chave sem expiração

createdAt

string<date-time>

Data e hora de criação da chave, em UTC (ISO 8601)

Visão Geral

Sub-keys

Cards

Tokens

3DS2 Malga

Charges

Sessions

Purchases

Subscriptions

Customers

Merchants

Providers

Vendors

Sellers

Payouts

Plans

Prepayment

Receipts

Flows

Webhooks

Settings

Criar sub-key

Onde usar sub-keys

Aplicações back-end

Aplicações client-side

Como funciona

Exemplo de criação

Tempo de validade (`expires`)

Escopos (`scope`)

Exemplos de escopo

Erros comuns

Authorizations

Body

Response

​Onde usar sub-keys

Aplicações back-end

Aplicações client-side

​Como funciona

​Exemplo de criação

​Tempo de validade (expires)

​Escopos (scope)

​Exemplos de escopo

​Erros comuns

Authorizations

Body

Response

Onde usar sub-keys

Como funciona

Exemplo de criação

Tempo de validade (`expires`)

Escopos (`scope`)

Exemplos de escopo

Erros comuns