Skip to main content
As Api Keys são tokens de acesso que permitem integrar a Chargefy com seus sistemas, parceiros ou automações. Cada organização gera as próprias chaves pelo dashboard, controla escopos e ambiente, e pode revogar a qualquer momento. Este guia cobre o ciclo de vida completo: criar, usar, revogar.

​
Requisitos

  • Você precisa ser owner ou admin da organização pra criar/revogar chaves. Membros comuns (member) não têm acesso ao menu
  • A tela fica em Settings → Chaves de API no dashboard

​
Criar uma chave

  1. Acesse https://app.chargefy.io/dashboard/<sua-org>/settings/api-keys
  2. Clique em Nova chave
  3. Preencha:
    • Nome — descritivo, ajuda depois a identificar (“Produção”, “Integração Stripe”, “Teste local”)
    • Ambiente — live (produção) ou test (sandbox; transações Zoop isoladas)
    • Permissões — read pra consultas, write pra criar/atualizar. Marque só o que precisar
  4. Clique em Criar chave
  5. Copie o token agora — ele aparece uma única vez. Botão Copiar copia pro clipboard; aperte também pra abrir no menu contextual
O token tem o formato ch_live_<43 chars> ou ch_test_<43 chars>. Guarde em:
  • Secret manager (AWS Secrets Manager, Google Secret Manager, Doppler, 1Password, Vault)
  • Variáveis de ambiente do seu servidor
  • Nunca em código-fonte Git, nunca em log, nunca em frontend/mobile
Se perder o token, não há recuperação. A plataforma só armazena o hash. Crie uma nova chave e revogue a antiga.

​
Listar chaves

A página principal mostra todas as chaves ativas da organização com:
  • Nome e prefixo mascarado (ex: ch_live_…xyz9)
  • Ambiente (live ou test)
  • Escopos concedidos
  • Data de criação e último uso
  • Data de expiração (se definida)
Marque Mostrar revogadas pra incluir chaves desativadas no histórico — útil pra auditoria.
A coluna “último uso” é atualizada em tempo real. Se uma chave aparece como “nunca usada” mas você tem certeza que a aplicação consumiu, o hash no seu código provavelmente está errado ou o header não chegou no servidor.

​
Usar a chave nas requests

​
Header recomendado

curl https://api.chargefy.io/v1/sales/ \
  -H "X-Chargefy-Api-Key: ch_live_AbCd1234…"

​
Bearer compatibility

Pra clients que só aceitam Authorization: Bearer: 
curl https://api.chargefy.io/v1/sales/ \
  -H "Authorization: Bearer ch_live_AbCd1234…"

​
SDK oficial

import { Chargefy } from '@chargefy/sdk'

const chargefy = new Chargefy({
  apiKey: process.env.CHARGEFY_API_KEY!,  // ou CHARGEFY_TEST_KEY
})

const sales = await chargefy.sales.list({ limit: 10 })
Exemplos completos por linguagem em SDKs.

​
Revogar uma chave

Na lista, clique em Revogar ao lado da chave alvo. Confirme no diálogo. Efeitos imediatos:
  • Próxima request com aquele token retorna 401 Unauthorized
  • A chave passa pra seção “Revogadas” (visível com o toggle)
  • Nome, último uso e metadata ficam preservados pra auditoria
Revogação não pode ser desfeita. Se precisar voltar atrás, crie uma chave nova e atualize a aplicação.

​
Quando revogar

  • Obrigatório: token vazou (commit acidental, laptop roubado, funcionário saiu)
  • Recomendado: rotação periódica (cada 90-180 dias), especialmente em ambiente live
  • Hygiene: chaves de integração descontinuada, não usadas há muito tempo

​
Workflow de rotação (zero downtime)

A plataforma não suporta rotação in-place — use este fluxo:
  1. Criar nova chave com mesmo nome + sufixo (ex: “Produção v2”)
  2. Atualizar a variável de ambiente da aplicação pra usar o novo token
  3. Deploy e confirmar (olhe “último uso” da chave nova)
  4. Revogar a chave antiga

​
Escopos

Os escopos definem o que a chave pode fazer:

​
read

Endpoints GET disponíveis:
  • /v1/subscriptions/*, /v1/customers/*
  • /v1/payouts/*, /v1/sales/*, /v1/transactions/*
  • /v1/products/*, /v1/checkout-links/*

​
write

Inclui tudo de read + endpoints de mutação:
  • POST /v1/customers/ — criar customer
  • POST /v1/transactions/ — criar transação (boleto/pix/card)
  • POST /v1/subscriptions/ — criar assinatura
  • POST /v1/refunds/ — estornar
  • PATCH / DELETE nos recursos acima

​
admin

Reservado pra operações críticas (gerenciar api keys via api key, etc). Não exposto na UI atualmente — se precisar, abra um ticket.

​
Expiração

Ao criar a chave você pode opcionalmente definir uma data de expiração. Após essa data:
  • Requests retornam 401 Unauthorized — api key expired
  • A chave aparece na lista com badge “expirada”
  • Você pode reativar criando uma nova — não há “renovar”
Útil pra:
  • Acessos temporários (pilotos de parceiros)
  • Acessos de equipe externa com escopo de tempo
  • Forçar rotação disciplinada

​
Boas práticas

Uma chave por integração

Criar chaves separadas por serviço/ambiente facilita revogação cirúrgica e auditoria (“quem usou o quê”).

Monitore last_used_at

Chaves não usadas há mais de 30 dias são candidatas a revoke preventivo.

Mantenha nomes descritivos

“Integração X — Produção — Rotacionada 2026-04” é melhor que “Produção 2”.

Princípio do menor privilégio

Só marque write se realmente precisa criar/atualizar. Leitura é suficiente pra dashboards de terceiro.

​
Troubleshooting

​
”Missing X-Chargefy-Api-Key header”

O header não chegou no servidor. Verifique:
  • O nome do header está exato (case-insensitive mas literal: X-Chargefy-Api-Key)
  • Proxies/middlewares não estão strippando o header
  • Authorization: Bearer ch_... também funciona como fallback

​
”Invalid api key”

O hash não bate. Causas comuns:
  • Token copiado com espaço extra no início/fim
  • Chave revogada ou soft-deleted
  • Prefixo errado (tem que ser ch_live_ ou ch_test_)

​
“Api key lacks required scope”

A chave não tem o escopo necessário pra aquele endpoint. Crie uma nova com o escopo apropriado e atualize a aplicação.

​
”Api key expired”

Ultrapassou a data de expiração. Crie uma nova.

​
429 Too Many Requests

Rate limit da plataforma. Implemente retry com backoff exponencial.

​
Próximos Passos

Autenticação

Resumo dos métodos de auth

SDK TypeScript

Usa a chave automaticamente

Webhooks

Configure webhooks assinados pra receber eventos

Sandbox

Teste com chave ch_test_ sem custo