| Superfície | Quem usa | Como autentica |
|---|---|---|
API pública (https://api.chargefy.io/v1) | Integrações server-to-server (seu backend, parceiros, automações) | API key no header Authorization: Bearer |
Dashboard (dashboard.chargefy.io) | Pessoas logadas no painel | Token de sessão (JWT) gerenciado pela própria UI |
Você quase sempre quer uma API key. O token de usuário existe só para a interface do dashboard funcionar — ele não é emitido para você colar em scripts. Se está escrevendo código que fala com a Chargefy de um servidor, use uma API key. Esta página foca nela.
https://api.chargefy.io/v1. Cada organização gera as próprias chaves no dashboard, em Settings → Chaves de API.
Tipos de chave
Existem dois tipos de API key, e eles se comportam de formas diferentes. A diferença não está no formato do token — está em sobre qual organização a chave pode agir.| Tipo | Age sobre | Header Organization | Caso de uso |
|---|---|---|---|
| Chave de organização | Somente a própria organização que emitiu a chave | Ignorado — a chave já fixa a org | Você integra a sua própria conta Chargefy |
| Chave de plataforma | Qualquer organização conectada ativa sob a plataforma | Obrigatório para escolher a org-alvo | Você opera uma plataforma/marketplace e age em nome das organizações conectadas |
Regra que não muda: uma chave de organização não pode sobrescrever a organização via header. Ela atua exclusivamente na própria org. Só a chave de plataforma usa o header
Organization para mirar uma organização conectada.Formato do token
ch_ e carrega o ambiente no prefixo:
| Prefixo | Ambiente | Comportamento |
|---|---|---|
ch_live_… | live | Cobranças reais. livemode: true nas respostas. |
ch_test_… | test | Sandbox. livemode: false nas respostas. |
Como usar
Envie o token no headerAuthorization com o esquema Bearer. Esta é a forma recomendada e compatível com qualquer cliente HTTP.
Header alternativo
Como alternativa aoAuthorization, a API também aceita o header dedicado X-Chargefy-Api-Key. Use quando o Authorization já estiver reservado para outra coisa no seu cliente.
Se ambos os headers chegarem, o
X-Chargefy-Api-Key tem prioridade. Em qualquer um dos dois, o token precisa começar com ch_ — caso contrário a requisição é tratada como sem credencial.Agindo como uma plataforma
Se a sua chave é de plataforma, ela não tem uma organização fixa: você escolhe a organização conectada a cada request com o headerOrganization.
Organization é o id de uma organização conectada e ativa sob a sua plataforma.
Header ausente em chave de plataforma
Header ausente em chave de plataforma
Sem
Organization, a plataforma não sabe sobre qual organização agir. O endpoint que exige escopo da org responde 400 pedindo o header.Organização não conectada ou inativa
Organização não conectada ou inativa
Se o
Organization aponta para uma org que não é conectada ativa da sua plataforma, a request é negada com 403.Header em chave de organização
Header em chave de organização
Uma chave de organização ignora o header
Organization — ela só age na própria org. Não é possível usá-la para “saltar” para outra organização.Escopos
Toda chave carrega um ou mais escopos que limitam o que ela pode fazer. Os escopos são fixos e validados a cada request.| Escopo | Permissão |
|---|---|
read | Listar e consultar recursos (GET) |
write | Criar, atualizar e desativar recursos (POST, DELETE) |
admin | Operações críticas (ex: gerenciar chaves via API). Não exposto no dashboard atualmente |
read aceita também chaves com write ou admin; um endpoint que exige write aceita write ou admin.
Siga o princípio do menor privilégio: crie chaves
read quando a integração só consulta dados, e reserve write para onde realmente precisa criar ou modificar.Obtendo uma chave
Entre como owner ou admin
Só papéis owner e admin da organização têm acesso ao menu de chaves. Membros comuns não.
Crie a chave
Clique em Nova chave, dê um nome descritivo (“Produção”, “Integração X”) e escolha os escopos.
Rotação e revogação
- Revogação instantânea — na lista de chaves, clique em Revogar. Requests com aquele token passam a retornar
401em milissegundos. - Rotação — não há “rotate in-place”. O fluxo de zero downtime é: criar a chave nova → atualizar a aplicação → confirmar pelo “último uso” → revogar a antiga.
- Último uso — a Chargefy registra o
last_used_atde cada chave. Chaves paradas há muito tempo são candidatas a revoke preventivo.
Respostas de autenticação
Toda falha segue o envelope de erro público:{ "error": { "code", "message", "type" } }, com chaves na ordem canônica.
Credencial ausente ou inválida — 401
Token não enviado, com formato errado, revogado, expirado ou que não bate com nenhuma chave.
Escopo insuficiente — 403
A chave é válida, mas não tem o escopo que o endpoint exige.
Organização inacessível — 403
A chave de plataforma apontou um Organization que não é uma organização conectada ativa.
As mensagens (
message) saem em inglês por padrão e servem para log do desenvolvedor. Faça branching de UX pelo code, não pela string da mensagem.Por que a base é api.chargefy.io
Sempre faça suas chamadas autenticadas por API key contra https://api.chargefy.io/v1. Esse host é o ponto de entrada oficial: ele aplica rate limiting, rastreamento de request e proteções de borda antes de a requisição chegar ao backend.
Segurança
E o token do dashboard?
Quando você usa o painel emdashboard.chargefy.io, a UI autentica com um token de sessão de usuário (JWT) que ela mesma gerencia, e o acesso aos dados é gateado por papel (owner/admin/member) e pelas regras de cada organização. Esse caminho é interno da interface: você não emite nem cola esse token em integrações. Para qualquer código server-to-server, o caminho é a API key descrita acima.
Próximos passos
Gerenciar Api Keys
Criar, listar, revogar e expirar chaves no dashboard.
Introdução à API
Base URL, paginação, envelope de erro e convenções.
Autenticação (API Reference)
O contrato de auth no nível da referência.
Webhooks
Verificar assinaturas e tratar retries.

