# 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](https://docs.infraio.xyz/pt-BR/api-reference/authentication). - 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](https://docs.infraio.xyz/pt-BR/webhooks/signature-verification). - 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 é uma boa prática porque documenta a intenção, mas leia o aviso abaixo antes de tratar escopo como uma fronteira de segurança. > **Warning:** > > **Os escopos ainda não são aplicados.** Um `sk_` vazado de *qualquer* > escopo pode chamar *qualquer* endpoint `/b2b/v1/*` para o seu lojista. > Uma chave `read` não é impedida de criar um reembolso. Escopos > restritos **não** limitam o dano de um vazamento ainda: para > planejamento de segurança, trate toda chave secreta como acesso total > e dependa de rotação e revogação rápidas (abaixo) para conter um > vazamento. ## Rotação 1. **Gere uma chave nova.** Dashboard → **Developers → API keys** → **+ Add key**. Escolha o escopo. O dashboard mostra o segredo **uma vez** — guarde imediatamente. 2. **Atualize as env vars** para o novo valor em todos os ambientes. Deploy. 3. **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. 4. **Revogue a chave antiga.** Mesma tela → menu kebab → **Revoke**. > **Warning:** > > **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: 1. **Dashboard → Developers → API keys → [chave] → Revoke now.** Efeito é instantâneo; sem período de tolerância. 2. Crie uma substituta e faça deploy. 3. 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 contact@lartech.xyz 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. - ❌ **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). A rotação é manual. ## Próximos passos - [Autenticação](https://docs.infraio.xyz/pt-BR/api-reference/authentication) — algoritmo exato de assinatura para chamadas B2B. - [Webhooks → Verificação de assinatura](https://docs.infraio.xyz/pt-BR/webhooks/signature-verification) — como `whsec_` é usado em eventos de entrada.