LLiccenDocs

Autenticação

Uma chave única por header. Sem OAuth, sem token de curta duração, sem troca de refresh.

O header

Envie a chave em x-api-key em toda chamada a /v1. Sem ela, ou com uma chave revogada, expirada ou de uma aplicação desativada, a resposta é 401.

cURL
curl https://api.transakto.io/v1/balance \
  -H "x-api-key: sk_live_..."

Aplicações e chaves

Uma aplicação representa um sistema que consome a API e agrupa várias chaves. Isso existe para permitir rotação: você gera a chave nova, troca no seu sistema e revoga a antiga sem derrubar as outras integrações da mesma conta.

A chave completa aparece uma única vez, na resposta da criação. A plataforma guarda apenas o hash, então não existe endpoint que a releia. Se perder, revogue e gere outra.

Escopos

Cada chave carrega uma lista de permissões. O endpoint recusa com 403 e código INSUFFICIENT_SCOPE quando falta alguma, informando qual.

Escopos disponíveis

charge:read
escopoopcional
Consultar e listar cobranças.
charge:write
escopoopcional
Criar cobranças.
payout:read
escopoopcional
Consultar e listar transferências.
payout:write
escopoopcional
Criar transferências.
balance:read
escopoopcional
Consultar o saldo.
account:read
escopoopcional
Consultar os dados da conta.
webhook:read
escopoopcional
Listar os webhooks da conta.
webhook:write
escopoopcional
Criar, editar e remover webhooks.
Resposta 403
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "A chave não tem permissão para esta operação.",
  "details": ["payout:write"]
}

Boas práticas

Dê a cada chave só o que ela precisa: um sistema que apenas gera cobranças não deveria conseguir enviar dinheiro para fora. Guarde a chave em variável de ambiente ou cofre de segredos, nunca no código nem no front-end. Defina data de expiração para chaves de teste.

A chave dá acesso ao dinheiro da conta. Se ela vazar, revogue imediatamente pela dashboard: a revogação vale a partir da próxima requisição.
AnteriorIntroduçãoPróximaIdempotência