Skip to main content
A Chargefy tem duas superfícies de autenticação, cada uma para um tipo de cliente. Saber qual você usa é o primeiro passo de qualquer integração.
SuperfícieQuem usaComo 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 painelToken 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.
A base de toda chamada autenticada é 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.
TipoAge sobreHeader OrganizationCaso de uso
Chave de organizaçãoSomente a própria organização que emitiu a chaveIgnorado — a chave já fixa a orgVocê integra a sua própria conta Chargefy
Chave de plataformaQualquer organização conectada ativa sob a plataformaObrigatório para escolher a org-alvoVocê 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_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
└┬─┘ └─┬┘ └────────────────┬────────────────┘
 │     │                   │
 │     │                   └── parte aleatória (base64url)
 │     └── ambiente (live | test)
 └── prefixo Chargefy
Todo token começa com ch_ e carrega o ambiente no prefixo:
PrefixoAmbienteComportamento
ch_live_…liveCobranças reais. livemode: true nas respostas.
ch_test_…testSandbox. livemode: false nas respostas.
O token aparece uma única vez, no momento da criação. A Chargefy guarda apenas um hash — não há como recuperar o texto claro depois. Se perder, revogue e crie uma nova.

Como usar

Envie o token no header Authorization com o esquema Bearer. Esta é a forma recomendada e compatível com qualquer cliente HTTP.
curl https://api.chargefy.io/v1/products \
  -H "Authorization: Bearer {{API_KEY}}"

Header alternativo

Como alternativa ao Authorization, 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.
curl https://api.chargefy.io/v1/products \
  -H "X-Chargefy-Api-Key: {{API_KEY}}"
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 header Organization.
curl https://api.chargefy.io/v1/products \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: id_123"
O valor de Organization é o id de uma organização conectada e ativa sob a sua 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.
Se o Organization aponta para uma org que não é conectada ativa da sua plataforma, a request é negada com 403.
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.
EscopoPermissão
readListar e consultar recursos (GET)
writeCriar, atualizar e desativar recursos (POST, DELETE)
adminOperações críticas (ex: gerenciar chaves via API). Não exposto no dashboard atualmente
Os escopos são hierárquicos: um nível maior satisfaz a exigência de um menor.
read  ⊂  write  ⊂  admin
Ou seja: um endpoint que exige 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

1

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.
2

Abra Settings → Chaves de API

No dashboard da Chargefy, em dashboard.chargefy.io.
3

Crie a chave

Clique em Nova chave, dê um nome descritivo (“Produção”, “Integração X”) e escolha os escopos.
4

Copie o token imediatamente

Ele aparece uma vez só. Guarde em secret manager ou variável de ambiente antes de fechar a tela.
O ciclo de vida completo (criar, listar, revogar, expirar, rotacionar) está em Gerenciar api keys.

Rotação e revogação

  • Revogação instantânea — na lista de chaves, clique em Revogar. Requests com aquele token passam a retornar 401 em 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_at de 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.
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "type": "authentication_error"
  }
}

Escopo insuficiente — 403

A chave é válida, mas não tem o escopo que o endpoint exige.
{
  "error": {
    "code": "permission_denied",
    "message": "The API key does not have the required scope.",
    "type": "invalid_request_error"
  }
}

Organização inacessível — 403

A chave de plataforma apontou um Organization que não é uma organização conectada ativa.
{
  "error": {
    "code": "permission_denied",
    "message": "The API key cannot access the requested organization.",
    "type": "invalid_request_error"
  }
}
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.
Requisições com API key que não passam por api.chargefy.io são rejeitadas com 401. O backend exige a assinatura de borda que só esse host adiciona — não tente chamar URLs internas de função diretamente.

Segurança

  • Nunca exponha API keys em código client-side (browser, mobile). Toda chamada autenticada por API key é server-side.
  • Armazene em secret manager ou variável de ambiente (CHARGEFY_API_KEY), nunca em código-fonte versionado nem em log.
  • Use sempre o menor escopo necessário, e separe live de test.
  • Revogue imediatamente qualquer chave comprometida (vazamento em log, commit, laptop roubado). A revogação é instantânea — não há janela de uso do token antigo.

E o token do dashboard?

Quando você usa o painel em dashboard.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.