Skip to main content
Uma API key é o token que autentica integrações server-to-server com a Chargefy. Cada chave pertence a uma organização, carrega escopos que limitam o que ela pode fazer e vive em um ambiente (live ou test). Você gera, lista e revoga chaves pelo dashboard, em Settings → Chaves de API.
Chave de organização ≠ chave de plataformaUma chave de organização atua apenas na própria organização e usa escopos read / write / admin. Uma chave de plataforma tem o escopo exclusivo platform_admin e age em organizações conectadas ativas, indicadas no header Organization. As duas têm o mesmo formato de token e o mesmo ciclo de vida — o que muda é o escopo e o alcance.
Este guia cobre o ciclo de vida completo: criar, usar, listar, revogar e rotacionar.

​
Requisitos

  • Você precisa ser owner ou admin da organização para criar, listar ou revogar chaves. Membros comuns (member) não enxergam o menu nem conseguem operar chaves.
  • A tela fica em Settings → Chaves de API no dashboard (https://dashboard.chargefy.io/dashboard/<sua-org>/settings/api-keys).
  • Para criar chaves de plataforma, a plataforma precisa estar ativa e ter o setup concluído (regras de split configuradas). Sem isso, a geração de chave é bloqueada.

​
Formato do token

O token segue sempre o mesmo formato: prefixo de ambiente + corpo aleatório. 
ch_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
└┬─┘ └─┬┘ └────────────────┬────────────────┘
 │     │                   │
 │     │                   └── 43 caracteres aleatórios (base64url)
 │     └── ambiente: live ou test
 └── prefixo Chargefy
ParteValorSignificado
Prefixoch_Identifica um token da Chargefy.
Ambientelive_ ou test_ch_live_ opera com dados reais; ch_test_ é isolado para sandbox.
Corpo43 caracteres32 bytes aleatórios em base64url, sem padding.
O token aparece uma única vez, no momento da criação. A plataforma guarda apenas o hash (SHA-256) — não há como recuperar o texto claro depois. Se perder, revogue e crie uma nova.

​
Ambientes: live vs test

Toda chave nasce em um ambiente, escolhido na criação (default live):
AmbientePrefixoQuando usar
livech_live_Produção — cobranças e dados reais.
testch_test_Sandbox — desenvolvimento e testes sem efeito financeiro real.
O ambiente da chave determina o campo livemode das respostas e dos webhooks: chave live produz livemode: true, chave test produz livemode: false. Mantenha chaves separadas por ambiente e nunca aponte produção para uma chave test.

​
Criar uma chave de organização

1

Abra a tela de chaves

Acesse Settings → Chaves de API como owner ou admin e clique em Nova chave.
2

Preencha os campos

  • Nome — descritivo, ajuda a identificar depois (Produção, Integração faturamento).
  • Permissões — marque read, write ou ambos. O default é read + write. Marque só o que a integração precisa.
  • Ambiente — live ou test.
  • Expiração (opcional) — uma data futura em que a chave deixa de funcionar.
3

Crie e copie o token

Clique em Criar chave e copie o token imediatamente — ele aparece uma única vez. Use o botão Copiar para levar ao clipboard.
Guarde o token em:
  • Secret manager (AWS Secrets Manager, Google Secret Manager, Doppler, 1Password, Vault).
  • Variáveis de ambiente do seu servidor (CHARGEFY_API_KEY).
  • Nunca em código-fonte versionado, em log, ou em frontend/mobile.

​
Criar uma chave de plataforma

Plataformas — organizações que orquestram pagamentos para organizações conectadas — usam um tipo de chave próprio, com escopo platform_admin. Ela é criada na configuração da plataforma, não na tela de chaves comum.
1

Conclua o setup da plataforma

A plataforma precisa estar ativa e ter as regras de split configuradas. Enquanto o setup não estiver concluído, a criação de chave fica bloqueada.
2

Gere a chave

Como owner ou admin da organização dona da plataforma, gere a chave informando um nome e o ambiente (live ou test).
3

Copie o token

Mesma regra: o token aparece uma vez só. Guarde em secret manager.
Chave de plataforma sempre nasce com o escopo platform_admin — não há seleção de escopo. Para atuar em uma organização conectada, envie o header Organization na request (veja Usar a chave).

​
Usar a chave nas requests

A chave pode ser enviada de duas formas, ambas aceitas: 
curl https://api.chargefy.io/v1/products \
  -H "Authorization: Bearer {{API_KEY}}"
Chave de plataforma indica a organização conectada-alvo no header Organization: 
curl https://api.chargefy.io/v1/products \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: id_123"
Para exemplos completos de cada endpoint, consulte a Referência da API. O resumo dos métodos de autenticação fica em Autenticação.

​
Escopos

Os escopos definem o que a chave pode fazer. Chaves de organização usam read / write / admin; chaves de plataforma usam platform_admin.
EscopoTipo de chavePermissão
readOrganizaçãoListar e consultar recursos (GET).
writeOrganizaçãoTudo de read + criar, atualizar e desativar recursos (POST, DELETE).
adminOrganizaçãoTudo de write + operações críticas. Reservado; não exposto na UI atualmente.
platform_adminPlataformaAtuar em organizações conectadas ativas via header Organization.
Os escopos de organização são hierárquicos: write inclui read, e admin inclui ambos. Um endpoint que exige read aceita também chaves write ou admin. Já platform_admin é exclusivo: chave de organização não satisfaz endpoint de plataforma, e vice-versa.

​
O que cada escopo cobre

Endpoints GET: consultar e listar customers, products, prices, payment-links, payment-intents, payment-methods, setup-intents, charges, files, organizations, onboarding-sessions.
Tudo de read mais os POST e DELETE que criam, atualizam ou desativam recursos — por exemplo POST /v1/customers, POST /v1/products, POST /v1/payment-links, além das ações e remoções documentadas em cada recurso.
Inclui tudo de write. Reservado para operações sensíveis. Não exposto no dashboard atualmente — se precisar, abra um ticket.
Exclusivo de chaves de plataforma. Permite operar em organizações conectadas ativas, indicadas no header Organization. Não satisfaz endpoints que exigem escopo de organização sem esse roteamento.
Siga o princípio do menor privilégio: crie chaves read quando a integração só consulta dados, e write apenas onde precisa criar ou modificar.

​
Listar chaves

A página principal mostra as chaves da organização com:
  • Nome e prefixo mascarado (ex: ch_live_…Qr2x, mostrando só os 4 últimos caracteres).
  • Escopos concedidos.
  • Ambiente (live / test).
  • Data de criação e último uso (last_used_at).
  • Data de expiração, quando definida.
Marque Mostrar revogadas para incluir chaves desativadas no histórico — útil para auditoria. Chaves revogadas preservam nome, último uso, quem revogou e o motivo.
A coluna “último uso” é atualizada a cada request autenticada. Se uma chave aparece como “nunca usada” mas você tem certeza de que a aplicação a consumiu, provavelmente o token está errado ou o header não chegou ao servidor.

​
Revogar uma chave

Na lista, clique em Revogar ao lado da chave alvo e confirme. Opcionalmente registre um motivo (vazou, rotação) para auditoria. Efeitos imediatos:
  • A próxima request com aquele token retorna 401 Unauthorized.
  • A chave passa para a seção “Revogadas” (visível com o toggle).
  • Nome, último uso, quem revogou, quando e por quê ficam preservados — a revogação é um soft-delete, não apaga o histórico.
Revogação não pode ser desfeita. Para voltar atrás, crie uma chave nova e atualize a aplicação. Tentar revogar uma chave já revogada retorna 409.

​
Quando revogar

SituaçãoUrgência
Token vazou (commit acidental, laptop roubado, funcionário saiu)Obrigatório, imediato
Rotação periódica (a cada 90–180 dias)Recomendado
Chave de integração descontinuada ou parada há muito tempoHigiene

​
Rotação sem downtime

A plataforma não suporta rotação in-place — siga este fluxo:
1

Criar

Gere uma chave nova com o mesmo nome + sufixo (Produção v2) e mesmos escopos/ambiente.
2

Atualizar

Aponte a variável de ambiente da aplicação para o novo token.
3

Deploy e confirmar

Faça o deploy e confira o “último uso” da chave nova subindo.
4

Revogar

Revogue a chave antiga.

​
Expiração

Na criação você pode definir uma data de expiração futura (ISO 8601). Depois dessa data:
  • Requests retornam 401 Unauthorized — api key expired.
  • A chave aparece na lista com badge “expirada”.
  • Não há “renovar” — crie uma nova chave para seguir.
Útil para acessos temporários (pilotos de parceiros), equipes externas com janela de tempo definida, ou para forçar rotação disciplinada.

​
Boas práticas

Uma chave por integração

Chaves separadas por serviço facilitam revogação cirúrgica e auditoria de “quem usou o quê”.

Separe live de test

Use ch_test_ em desenvolvimento e ch_live_ em produção. Nunca aponte produção para uma chave de teste.

Monitore o último uso

Chaves paradas há mais de 30 dias são candidatas a revogação preventiva.

Menor privilégio

Só conceda write quando a integração realmente precisa criar ou modificar. Leitura basta para dashboards de terceiros.

​
Troubleshooting

O header não chegou ao servidor. Verifique se a request usa Authorization: Bearer <token> ou X-Chargefy-Api-Key: <token>, e que proxies/middlewares não estão removendo o header.
O hash não bate. Causas comuns: token copiado com espaço extra, chave revogada/expirada, ou prefixo incorreto (precisa começar com ch_).
A chave não tem o escopo do endpoint. Crie uma nova com o escopo apropriado e atualize a aplicação. Lembre que platform_admin não satisfaz endpoints de organização sem o header Organization.
A data de expiração passou. Crie uma nova chave.
Rate limit da plataforma. Implemente retry com backoff exponencial.

​
Próximos passos

Autenticação

Resumo dos métodos de auth e respostas de erro.

Webhooks

Verifique webhooks assinados.

API Reference

Consulte os endpoints públicos.