> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Gerenciar API keys
> Use chaves publicáveis no browser e chaves secretas no backend.
O Dashboard mostra dois tipos de chave, ambos separados por ambiente:
| Tipo | Prefixo | Onde usar | Poder de acesso |
| ---------- | ------------------------- | ----------------------- | ----------------------------------------------------------------------- |
| Publicável | `pk_test_*` / `pk_live_*` | Browser com Chargefy.js | Identifica conta e ambiente; exige também o `client_secret` do recurso. |
| Secreta | `ch_test_*` / `ch_live_*` | Backend e jobs | Lê e altera recursos conforme os escopos concedidos. |
## 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:
```js theme={"theme":"css-variables"}
const chargefy = Chargefy("pk_test_...");
```
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](/api-reference/authentication).
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
Clique em **Nova chave** e use um nome que identifique o serviço e o
ambiente, como `Faturamento — produção`.
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`.
Escolha `test` ou `live`. Se o acesso for temporário, defina também uma data
de expiração.
Copie o token antes de fechar a tela. Depois disso, ele não pode ser exibido
novamente.
| Ambiente | Prefixo secreto | Uso |
| -------- | --------------- | ------------------------------------------------- |
| Teste | `ch_test_` | Desenvolvimento e sandbox, com `livemode: false`. |
| Produção | `ch_live_` | Dados e cobranças reais, com `livemode: true`. |
Dados e credenciais não atravessam ambientes. Veja os cenários disponíveis em [Sandbox](/api-reference/sandbox).
## Credencial secreta e ID da chave
Cada API key possui dois valores diferentes:
| Valor | Formato | Uso |
| -------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Credencial secreta | `ch_test_...` ou `ch_live_...` | Autentica chamadas no header. É exibida uma única vez e deve ficar no seu secret manager. |
| ID público do objeto | `key_` seguido por 12 caracteres | Identifica a chave no Dashboard, nos objetos `request` e em filtros. Não autentica chamadas e não é um segredo. |
Para consultar somente as requests feitas por uma chave específica, envie o ID público no filtro `api_key`:
```bash theme={"theme":"css-variables"}
curl -X GET "https://api.chargefy.io/v1/requests?api_key=key_Y4MsH6YgqSMj" \
-H "Authorization: Bearer {{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`.
O Chargefy for Platforms precisa estar ativo e com as regras de split
configuradas.
Como **owner** ou **admin**, informe um nome e escolha o ambiente.
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](/api-reference/authentication#chargefy-for-platforms-operar-organizacoes-filhas).
## 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
| Situação | Ação recomendada | Efeito |
| --------------------- | ------------------------------------------- | ------------------------------------------------ |
| Acesso temporário | Defina uma expiração ao criar a chave. | Após a data, novas requests retornam `401`. |
| Suspeita de vazamento | Revogue imediatamente e crie outra. | A credencial deixa de autenticar novas requests. |
| Integração desativada | Revogue a chave que pertencia ao serviço. | O histórico continua disponível para auditoria. |
| Rotação programada | Crie a substituta antes de revogar a atual. | Permite a troca sem indisponibilidade. |
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
Use o mesmo ambiente e apenas os escopos necessários.
Troque o valor no secret manager e publique a configuração.
Faça uma chamada autenticada e confira o horário de último uso da chave nova
no Dashboard.
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
| Sintoma | Verifique |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| `401 authentication_failed` | Token copiado por completo, ambiente correto, chave ativa e header sem espaços extras. |
| `401` após a data configurada | A chave expirou; crie outra e atualize a aplicação. |
| `403 permission_denied` | O escopo da chave não permite a operação. |
| A chave aparece como “nunca usada” | A aplicação pode estar usando outro segredo ou removendo o header antes do envio. |
Veja os headers, escopos e erros de contexto em [Autenticação](/api-reference/authentication). Para armazenamento, logs e resposta a incidentes, consulte [Autenticação e segurança](/api-reference/authentication).
## Próximos passos
Envie a credencial e escolha o contexto correto.
Proteja credenciais, dados de cartão, webhooks e logs.
Teste a integração sem efeito financeiro real.
Verifique eventos assinados no seu servidor.