Chaves de API

Cada conta tem uma chave secreta e uma chave publicável por ambiente, além de um segredo de assinatura por endpoint de webhook. Hoje só existe o ambiente de teste, então toda chave que você consegue começa com um prefixo test.

• Chave secreta: autentica toda chamada à API feita pelo seu servidor. Trate-a como uma senha.
• Chave publicável: pode ir numa página, mas está reservada para uso futuro no navegador. Nenhum endpoint documentado a aceita ainda (veja Autenticação).
• Segredo de assinatura de webhook: confirma que uma entrega de webhook veio da KrokoPay. Não é uma chave de API e não chama a API (veja Webhooks).

O prefixo diz o que é a chave antes de você usá-la. Scanners de código e revisores conseguem reconhecê-lo, e o seu próprio código pode conferi-lo na inicialização.

Abra Desenvolvedores → Chaves de API no painel. A chave secreta fica mascarada até você revelá-la; copie direto para o seu ambiente em vez de colar em chats ou chamados. Os segredos de assinatura aparecem em cada endpoint, em Desenvolvedores → Webhooks.

Guarde a chave secreta numa variável de ambiente ou no gerenciador de segredos da sua plataforma, e leia-a só no código do servidor. Deixe os arquivos de ambiente locais fora do controle de versão.

# Server-side only. Never commit this file.KROKOPAY_SECRET_KEY=kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b

Confira a chave uma vez na inicialização, para que uma chave ausente ou errada falhe de forma clara nos seus logs, e não como um 401 na frente do comprador:

// server/krokopay.ts: read the key once, on the server, and fail fast.const key = process.env.KROKOPAY_SECRET_KEY;​if (!key) {  throw new Error("KROKOPAY_SECRET_KEY is not set");}if (!/^kp_test_sk_[0-9a-f]{24}$/.test(key)) {  throw new Error("KROKOPAY_SECRET_KEY must be a test secret key (kp_test_sk_…)");}​export async function krokopay(path: string, init: RequestInit = {}) {  return fetch(`https://api.krokopay.app/v1${path}`, {    ...init,    headers: { ...init.headers, Authorization: `Bearer ${key}` },  });}

• Nunca coloque a chave secreta em código de front-end, apps de celular, repositórios públicos ou URLs.
• Dê a cada serviço que chama a API acesso à variável, e não uma cópia do valor na configuração dele.
• Nunca cole a chave em chats, chamados ou capturas de tela. Compartilhe o acesso ao gerenciador de segredos.

Trocar uma chave cria uma nova e revoga a antiga na hora. Não existe período de convivência, então qualquer requisição que ainda use a chave antiga recebe 401 invalid_api_key a partir desse momento.

1. 1

   Passo 1: Prepare o deploy

   Garanta que você consegue atualizar a KROKOPAY_SECRET_KEY e reiniciar o servidor de uma vez.

2. 2

   Passo 2: Troque a chave

   Em Desenvolvedores → Chaves de API, escolha trocar a chave secreta e copie o novo valor.

3. 3

   Passo 3: Atualize e reinicie

   Coloque o novo valor em todos os ambientes que o usam e reinicie, depois acompanhe os logs atrás de respostas 401.

1. Troque a chave secreta imediatamente. Não espere descobrir como ela vazou.
2. Publique a nova chave em todos os lugares onde ela é usada.
3. Revise as requisições recentes em Desenvolvedores → Logs e as suas cobranças atrás de algo que você não criou.
4. Apague o valor antigo de onde ele ficou exposto, inclusive do histórico de commits e de documentos compartilhados.

• A chave secreta é lida de uma variável de ambiente, só no servidor.
• Os arquivos de ambiente estão no .gitignore.
• O seu código confere o prefixo kp_test_sk_ na inicialização.
• Você sabe trocar a chave e publicar de novo num passo só.
• Os logs nunca contêm a chave completa.