Skip to main content

​
Métodos de Autenticação

A API da Garu suporta dois métodos de autenticação:
MétodoFormato do HeaderCaso de Uso
Chave de APIBearer sk_live_xxx ou Bearer sk_test_xxxIntegrações servidor-para-servidor
Token JWTBearer eyJhbG...Dashboard e aplicações frontend
Para integrações de API, recomendamos usar Chaves de API por serem mais simples e seguras para comunicação entre servidores.

​
Obtendo sua Chave de API

1

Acesse o Dashboard

Faça login no Dashboard da Garu
2

Navegue até Desenvolvedores

Vá para Configurações → Desenvolvedores
3

Crie uma nova chave

Clique em Criar chave de API
4

Selecione o ambiente

Escolha o tipo de chave:
  • sk_test_ - Para desenvolvimento e testes (sem cobranças reais)
  • sk_live_ - Para produção (processa pagamentos reais)
5

Salve sua chave

Importante: Salve a chave imediatamente. Ela só será exibida uma vez!

​
Usando sua Chave de API

Inclua sua chave de API no header Authorization de todas as requisições: 
curl -X GET https://garu.com.br/api/products \
  -H "Authorization: Bearer sk_test_abc123xyz..."

​
Exemplos por Linguagem

const response = await fetch('https://garu.com.br/api/products', {
  headers: {
    'Authorization': `Bearer ${process.env.GARU_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

​
Ambientes

AmbientePrefixo da ChaveDescrição
Sandboxsk_test_Ambiente de testes. Nenhuma cobrança real é processada.
Produçãosk_live_Ambiente de produção. Processa pagamentos reais.
Nunca use chaves sk_live_ em ambientes de desenvolvimento ou testes. Cobranças reais serão processadas!

​
Boas Práticas de Segurança

Chaves de API devem ser usadas apenas em código servidor. Nunca inclua chaves em JavaScript frontend, aplicativos móveis ou repositórios públicos.
Armazene suas chaves em variáveis de ambiente, não diretamente no código:
# .env
GARU_API_KEY=sk_test_abc123xyz...
Crie chaves separadas para desenvolvimento, staging e produção. Isso facilita a rotação e auditoria.
Se uma chave for exposta, revogue-a imediatamente no Dashboard e crie uma nova.
A API tem limite de 100 requisições por minuto. Implemente backoff exponencial para lidar com erros 429.

​
Erros de Autenticação

​
401 Unauthorized

{
  "statusCode": 401,
  "message": "API key is required"
}
Causas comuns:
  • Header Authorization ausente
  • Prefixo Bearer faltando
  • Chave de API inválida ou expirada
Solução: Verifique se o header está no formato correto: Authorization: Bearer sk_xxx

​
403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions"
}
Causas comuns:
  • Chave de API não tem permissão para o endpoint
  • Tentando acessar recursos de outro vendedor
Solução: Verifique as permissões da sua chave no Dashboard.

​
Testando sua Autenticação

Use este comando para verificar se sua chave está funcionando: 
curl -X GET https://garu.com.br/api/products \
  -H "Authorization: Bearer sk_test_sua_chave_api" \
  -w "\nHTTP Status: %{http_code}\n"
Se você receber HTTP Status 200, sua autenticação está configurada corretamente!

​
Próximos Passos

Criar Produtos

Aprenda a criar seu primeiro produto

Link de Pagamento

Obtenha o link para receber pagamentos