Chaves de API

Três tipos de credenciais, três modelos de ameaça.

`pk_` — Publicável

Projetada para ir para o navegador. Enviada como o header X-Client-ID em toda requisição B2B assinada e também embutida no bundle do SDK para abrir checkouts do lado do cliente.
Identifica a sua conta; não pode criar sessões, ler dados de outros lojistas nem acionar nada destrutivo.
Uma chave publicável vazada é um evento de baixa severidade.

`sk_` — Secreta (chave de assinatura HMAC)

A chave de assinatura HMAC-SHA256 para todas as chamadas B2B da API — veja Autenticação.
Nunca viaja pela rede. Só a assinatura derivada por requisição viaja. Então você só precisa se preocupar com vazamentos na camada de armazenamento (env vars, git, logs), não na camada de transporte.
Só servidor. Nunca deve aparecer num bundle do navegador, repo público, screenshot ou mensagem de chat.
Uma chave secreta vazada é um evento de alta severidade.

`whsec_` — Segredo de assinatura de webhook

Usado para verificar a assinatura em entregas de webhook de entrada da gente para o seu servidor. Veja Verificação de assinatura.
Separado por endpoint de webhook — se você tem 3 endpoints registrados, você tem 3 segredos whsec_ distintos. O ambiente é codificado no prefixo: whsec_live_… / whsec_test_….
Só servidor. Como o sk_, nunca viaja pela rede — só é usado para verificar HMACs localmente.
A rotação tem uma janela de tolerância de 24 horas. Clique em Rotate e o segredo anterior continua sendo aceito por 24h ao lado do novo (entregas levam tanto X-Signature quanto X-Signature-Prev), para que você possa redeployar o seu verificador sem segurar o tráfego.
Revelar o segredo existente está disponível, condicionado a 2FA recente e registrado no log de auditoria — para o caso em que o segredo foi perdido e a rotação não é aceitável. A postura padrão do dashboard é “rotacionar, não revelar”.
Um segredo de webhook vazado deixa um atacante falsificar eventos para a sua URL. Severidade média a alta, dependendo de quanto você confia no payload do evento.

Escopos

Chaves secretas são escopadas. O dashboard te deixa criar chaves com um destes bundles de escopo:

Escopo	Pode	Usado para
`read`	Listar/ler pedidos, sessões, reembolsos, saldos	Integrações somente leitura (analytics, BI)
`write_order`	Tudo de `read` + criar sessões, criar pedidos, cancelar pedidos	Backend da loja
`write_refund`	Tudo de `read` + criar reembolsos, marcar reembolsos executados	Ferramentas de suporte ao cliente
`webhook_manage`	Tudo de `read` + gerenciar endpoints de webhook	Ferramentas de DevOps

Uma chave “full access” padrão pega os quatro. Criar chaves por-propósito ainda é boa higiene — documenta a intenção e te deixa pronto para quando a aplicação chegar — mas leia o aviso abaixo antes de tratar escopo como uma fronteira de segurança.

Escopos são consultivos hoje — eles não são aplicados no gateway. O gateway verifica a assinatura HMAC da chave e injeta a sua identidade de lojista (X-Merchant-ID / X-Merchant-Domain) para os serviços downstream, mas não propaga nem checa o escopo da chave. Na prática isso significa que um sk_ vazado de qualquer escopo pode chamar qualquer endpoint /b2b/v1/* para o seu lojista — uma chave read não é de fato impedida de criar um reembolso. Então escopos restritos não limitam o raio de impacto ainda: para planejamento de breach trate toda chave secreta como full-access e dependa de rotação + revogação rápidas (abaixo) como a sua contenção real. Aplicação por escopo está no roadmap.

Rotação

Gere uma chave nova. Dashboard → Developers → API keys → + Add key. Escolha o escopo. O dashboard mostra o segredo uma vez — guarde imediatamente.
Atualize as env vars para o novo valor em todos os ambientes. Deploy.
Verifique o tráfego. O dashboard mostra contagens de requisição por chave em tempo real. Espere a contagem da chave antiga cair para zero.
Revogue a chave antiga. Mesma tela → menu kebab → Revoke.

Não existe janela automática de sobreposição hoje — uma vez que você revoga uma chave, qualquer requisição em voo assinada com ela pega 401. Planeje a sua rotação adequadamente: faça deploy da chave nova primeiro, drene o tráfego da antiga, depois revogue.

Revogação emergencial

Se uma chave vazou (no histórico do git, num bundle público, num stack trace logado, num relatório de pen-test de parceiro) — revogue imediatamente, mesmo ao custo de algumas requisições falhando. Melhor falhar ruidosamente do que deixar um atacante com uma credencial válida.

Passos:

Dashboard → Developers → API keys → [chave] → Revoke now. Efeito é instantâneo; sem período de tolerância.
Crie uma substituta e faça deploy.
Audite a atividade recente — o dashboard mostra os últimos 30 dias de requisições por chave com IPs e endpoints atingidos.

Se você suspeita que o breach é maior do que uma chave, contate [email protected] para:

Pegar um export completo do log de auditoria para a sua conta de lojista
Rotacionar segredos de webhook em massa
Opcionalmente congelar a conta enquanto você investiga

Boas práticas de armazenamento

Só env vars. Nunca cometa segredos no git, nem num .env.example que diga “REPLACE ME”.
Chaves por ambiente. sk_test_… e sk_live_… diferentes para dev/staging/prod, vindos do seu gerenciador de segredos (AWS Secrets Manager, Vault, Doppler, …).
Restrinja o acesso às env vars. No Kubernetes, monte como um Secret, não um ConfigMap. No Vercel/Netlify, use escopo de env var em vez de globals do projeto inteiro.
Não logue requisições com bodies. Mesmo em debug — a sua assinatura HMAC em X-Signature é de uso único, mas o payload de negócio pode conter PII.

O que NÃO é suportado hoje

❌ Allowlist de IP para chaves secretas. No roadmap.
❌ Tokens escopados por usuário no estilo OAuth. O modelo atual de chave é por-lojista, não por-usuário.
❌ Rotação automática de chave (por exemplo, rotação semanal imposta pela plataforma). Manual hoje.

Próximos passos

Autenticação — algoritmo exato de assinatura para chamadas B2B.
Webhooks → Verificação de assinatura — como whsec_ é usado em eventos de entrada.