Skip to main content
O Dashboard mostra dois tipos de chave, ambos separados por ambiente:

​
Chaves publicáveis

As chaves pk_* já existem para a organização e ficam sempre visíveis em Developers → Chaves de API. Inicialize o SDK com a chave do ambiente:
Uma chave publicável pode ser incluída no JavaScript do site. Ela não lista customers, pagamentos ou cadastros e não substitui uma chave secreta. Para consultar ou concluir um cadastro de cartão, o browser também precisa do client_secret exato daquele setup_intent.
Publicável não significa que ela autoriza a conta. O acesso ao cadastro exige também o client_secret correspondente. Não exponha esse secret em analytics ou logs e nunca coloque uma chave secreta ch_* no browser.

​
Chaves secretas

Uma chave ch_* autentica chamadas server-to-server. Para saber quais headers e escopos enviar em cada request, consulte Autenticação.
O token completo aparece uma única vez, logo após a criação. Copie-o nesse momento e guarde-o em um secret manager ou variável de ambiente protegida.

​
Antes de começar

  • Entre no Dashboard como owner ou admin da organização.
  • Abra Developers → Chaves de API.
  • Decida se a chave será de teste ou produção e qual integração vai usá-la.

​
Criar uma chave secreta da sua organização

1

Crie uma nova chave

Clique em Nova chave e use um nome que identifique o serviço e o ambiente, como Faturamento — produção.
2

Escolha o acesso necessário

Selecione somente os escopos exigidos pela integração. Uma rotina de consulta precisa de read; uma integração que cria ou altera recursos precisa de write.
3

Defina ambiente e expiração

Escolha test ou live. Se o acesso for temporário, defina também uma data de expiração.
4

Copie e armazene o token

Copie o token antes de fechar a tela. Depois disso, ele não pode ser exibido novamente.
Dados e credenciais não atravessam ambientes. Veja os cenários disponíveis em Sandbox.

​
Credencial secreta e ID da chave

Cada API key possui dois valores diferentes: Para consultar somente as requests feitas por uma chave específica, envie o ID público no filtro api_key:
Em 1º de agosto de 2026, os IDs públicos de API keys existentes deixaram os formatos legados sk_live_... e sk_test_... e passaram para key_.... As credenciais secretas ch_live_... e ch_test_... não foram alteradas. Se sua integração armazenava o ID público para filtrar requests, atualize esse valor; nenhuma rotação da credencial é necessária.

​
Chargefy for Platforms: criar uma chave

Este recurso só está disponível para Chargefy for Platforms. Ter um SaaS, aplicativo ou marketplace próprio não significa que sua conta usa esse produto. Esta seção se aplica a quem opera pagamentos para suas organizações filhas.
A chave do Chargefy for Platforms é criada na configuração da plataforma e usa o escopo exclusivo platform_admin.
1

Conclua a configuração

O Chargefy for Platforms precisa estar ativo e com as regras de split configuradas.
2

Gere a chave

Como owner ou admin, informe um nome e escolha o ambiente.
3

Copie e proteja o token

O token também aparece uma única vez. Guarde-o no backend em um secret manager.
Para atuar em uma organização filha, siga as regras de URL e do header Organization descritas em Autenticação do Chargefy for Platforms.

​
Acompanhar as chaves

A lista do Dashboard mostra:
  • nome e trecho mascarado do token;
  • ambiente e escopos;
  • criação e último uso;
  • expiração, quando configurada;
  • estado ativo, expirado ou revogado.
Ative Mostrar revogadas para consultar o histórico. Use “último uso” para confirmar uma implantação nova e identificar credenciais que deixaram de ser necessárias.

​
Expirar ou revogar

Revogação não pode ser desfeita. Apagar o segredo de um commit, log ou ticket não torna a credencial segura novamente.

​
Rotacionar sem downtime

1

Crie a substituta

Use o mesmo ambiente e apenas os escopos necessários.
2

Atualize a aplicação

Troque o valor no secret manager e publique a configuração.
3

Confirme o novo uso

Faça uma chamada autenticada e confira o horário de último uso da chave nova no Dashboard.
4

Revogue a anterior

Remova a chave antiga somente depois de confirmar que nenhum processo ainda depende dela.

​
Checklist de segurança

  • Use uma chave por integração para facilitar auditoria e revogação.
  • Nunca coloque chaves secretas ch_* em browser, aplicativo mobile, URL, log ou repositório. Chaves publicáveis pk_* foram feitas para o frontend.
  • Separe desenvolvimento, staging e produção.
  • Conceda o menor escopo necessário.
  • Monitore último uso, expiração e chaves sem atividade.
  • Revogue imediatamente qualquer credencial exposta.

​
Se a chave não funcionar

Veja os headers, escopos e erros de contexto em Autenticação. Para armazenamento, logs e resposta a incidentes, consulte Autenticação e segurança.

​
Próximos passos

Autenticação

Envie a credencial e escolha o contexto correto.

Autenticação e segurança

Proteja credenciais, dados de cartão, webhooks e logs.

Sandbox

Teste a integração sem efeito financeiro real.

Webhooks

Verifique eventos assinados no seu servidor.