Chaves de API - AbacatePay

A chave de API é sua credencial de acesso à AbacatePay. Ela identifica sua conta e autoriza cada requisição enviada para a nossa API. Sem uma chave válida, nenhum pedido será aceito.

Toda requisição para a API da AbacatePay deve incluir sua chave no header Authorization. A chave também define o ambiente — uma chave de Dev mode simula transações, uma chave de Produção processa valores reais. Você não muda de URL para mudar de ambiente; muda a chave.

O que você pode fazer com suas chaves

As chaves de API são gerenciadas diretamente pelo dashboard. Com elas, você pode:

Ver todas as chaves ativas
Criar novas chaves para diferentes projetos
Revogar chaves comprometidas ou que não são mais usadas

Dev mode x Produção

Todas as requisições usam o mesmo endpoint api.abacatepay.com.
O ambiente é definido pela chave utilizada:

Chaves criadas em Dev mode → transações simuladas
Chaves criadas em Produção → transações reais

Saiba mais sobre o ambiente de testes aqui.

Erro de Autenticação (401)

Você receberá um HTTP 401 quando:

A chave não for enviada no header
A chave estiver incorreta
A chave tiver sido revogada

Permissões da chave de API

Além de identificar sua conta, a chave de API define quais recursos você pode acessar. Quase todos os endpoints da API exigem que a chave tenha a permissão correspondente; sem ela, a requisição será recusada (por exemplo, com 403 Forbidden). Ao criar ou gerenciar chaves no dashboard, você pode atribuir apenas as permissões necessárias para cada integração — por exemplo, uma chave só para leitura de clientes ou outra só para criar cobranças. Isso melhora a segurança e o princípio do menor privilégio. Exceção: o endpoint de MRR (/public-mrr/mrr) é público e não exige permissão de chave.

Permissões disponíveis

Recurso	Permissões
Checkout	`CHECKOUT:CREATE`, `CHECKOUT:READ`, `CHECKOUT:DELETE`
Coupon	`COUPON:CREATE`, `COUPON:READ`, `COUPON:UPDATE`, `COUPON:DELETE`
Customer	`CUSTOMER:CREATE`, `CUSTOMER:READ`, `CUSTOMER:DELETE`
Product	`PRODUCT:CREATE`, `PRODUCT:READ`, `PRODUCT:DELETE`
Store	`STORE:READ`, `STORE:CREATE`, `STORE:DELETE`
Withdraw	`WITHDRAW:CREATE`, `WITHDRAW:READ`
Connect	`CONNECT:READ`, `CONNECT:CREATE`, `CONNECT:DELETE`

Cada endpoint da documentação indica qual permissão é necessária no topo da página.

Troubleshooting

401 Unauthorized — o que verificar

Causas mais comuns, em ordem de frequência:

O header Authorization: Bearer SUA_CHAVE não está sendo enviado
A chave foi copiada com espaços extras ou caracteres invisíveis
A chave foi revogada no dashboard
Você está usando uma chave de Dev mode em uma URL que exige produção (ou vice-versa)

Para confirmar que a chave está funcionando, teste diretamente:

curl https://api.abacatepay.com/v2/stores/get \
  -H "Authorization: Bearer SUA_CHAVE"

403 Forbidden — permissão ausente

A chave existe e é válida, mas não tem a permissão para o recurso solicitado. Acesse o dashboard, edite a chave e adicione a permissão necessária. Consulte a tabela de permissões acima para saber qual adicionar.

Chave de Dev mode vs Produção — qual estou usando?

No dashboard, as chaves de Dev mode têm um indicador visual. Se você não tem certeza, verifique o campo devMode em qualquer resposta da API — true significa Dev mode, false significa Produção.

Boas práticas de segurança

Armazene suas chaves em variáveis de ambiente
Nunca publique sua chave em repositórios ou grupos
A AbacatePay nunca solicitará sua chave
Revogue imediatamente qualquer chave que possa ter vazado

Como criar uma chave de API

Siga os passos abaixo no dashboard:

Acesse a seção de Integração

Interface da plataforma AbacatePay mostrando o botão de criação de chave

Clique em 'Criar Chave'

Inicie a criação de uma nova chave de API.

Adicione uma descrição

Formulário de criação de chave com campo de descrição

Identifique a chave

Use nomes claros, como “Loja Principal” ou “Ambiente de testes”.

Copie a chave gerada

Guarde com segurança

Copie a chave e salve em um local seguro ou gerenciador de segredos.

Depois disso, você já pode enviar requisições:

curl -X POST https://api.abacatepay.com/v2/transparents/create \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  --data '{
    "amount": 1000,
    "method": "PIX"
  }'

Nota Importante

O mesmo endpoint api.abacatepay.com é usado para o ambiente de desenvolvimento e produção. O ambiente é determinado automaticamente pela chave de API utilizada na requisição.

​O que você pode fazer com suas chaves

Dev mode x Produção

Erro de Autenticação (401)

​Permissões da chave de API

​Permissões disponíveis

​Troubleshooting

​Boas práticas de segurança

​Como criar uma chave de API

Clique em 'Criar Chave'

Identifique a chave

Guarde com segurança

Nota Importante

O que você pode fazer com suas chaves

Permissões da chave de API

Permissões disponíveis

Troubleshooting

Boas práticas de segurança

Como criar uma chave de API