Chaves de API

Publishable, secret, restricted — três famílias de chaves com escopos distintos. Rotação, secret scanning, env vars.

A Zhex usa três famílias de chaves com escopos distintos. Use sempre a mais restrita possível.

As três famílias

Tipo	Prefixo	Onde usar	O que pode
Publishable	`zk_test_` / `zk_live_`	Frontend, mobile, qualquer ambiente público	Criar `Token` via `zhex.js`. Só isso.
Secret	`zsk_test_` / `zsk_live_`	Apenas servidor backend	Tudo: criar `PaymentIntent`, refund, listar transações, ler dados de cliente.
Restricted	`zrk_live_*`	Workers, ferramentas internas	Apenas escopos explícitos (`payments:read`, `refunds:write`, etc.). Use em vez de `zsk_*` quando possível.

Test vs. Live

*_test_* — modo sandbox. Tocar adquirente real é impossível. Use cartões de teste, PIX simulado.
*_live_* — modo produção. Movimenta dinheiro real.

Visualmente diferenciados no dashboard com banner amarelo no test mode — impossível confundir.

Restricted keys

zrk_live_* permite escopo granular:

zrk_live_xxxxxxxxxxxxxxxxxxxxxxxx
  └── scopes: ["payments:read", "events:read"]

Casos de uso:

Worker de reconciliation → payments:read + transfers:read
Webhook replay tool → events:read + webhook_endpoints:read
Dashboard interno BI → payments:read + customers:read
Pipeline ETL → escopo zero de write — só leitura

Comprometida, o blast radius é mínimo: atacante não consegue criar refund, alterar webhook ou cancelar assinatura.

Escopos disponíveis

payments:read · payments:write
refunds:read · refunds:write
customers:read · customers:write
products:read · products:write
subscriptions:read · subscriptions:write
events:read
webhook_endpoints:read · webhook_endpoints:write
balance:read · payouts:read · payouts:write
disputes:read · disputes:write

Rotação

// 1. Crie nova chave no dashboard
// 2. Deploy do app com a nova chave (mantém ambas ativas)
// 3. Verifique logs por 24h: nenhuma request com chave antiga
// 4. Revoke a chave antiga no dashboard

Chave	Frequência recomendada
`zsk_live_*`	90 dias
`whsec_live_*`	180 dias
`zrk_live_*`	90 dias
`zk_live_*`	Apenas se vazada (publishable é pública por design)

O dashboard permite 2 chaves secretas ativas simultaneamente durante a transição.

Secret scanning

A Zhex é parceira do GitHub Secret Scanning Partner Program. Se você comitar uma zsk_live_* em repo público:

GitHub detecta em segundos via regex partner.
Notifica a Zhex.
A chave é revogada automaticamente em < 5 minutos.
Você recebe email avisando.

Em repos privados, recomendamos rodar gitleaks ou trufflehog na CI. Nossas regras cobrem zk_*, zsk_*, zrk_* e whsec_*.

Env vars + secret manager

Nunca hardcode. Sempre via env var, idealmente injetada por secret manager:

// ❌ ERRADO
const SECRET = 'zsk_live_xxxxx';
await fetch(URL, { headers: { Authorization: `Bearer ${SECRET}` } });

// ✅ CERTO
const SECRET = process.env.ZHEX_SECRET_KEY!;
if (!SECRET) throw new Error('ZHEX_SECRET_KEY ausente');
await fetch(URL, { headers: { Authorization: `Bearer ${SECRET}` } });

Secret managers recomendados:

AWS Secrets Manager + IAM role (sem long-lived credential)
HashiCorp Vault
Doppler (DevEx superior, free tier ok pra times pequenos)
GCP Secret Manager
1Password Secrets Automation (bom para times pequenos)

Em emergência

Se você acidentalmente expôs uma zsk_*:

Vá imediatamente em Developers → API keys no dashboard.
Clique Revoke na chave comprometida.
A chave morre em < 5s globalmente.
Crie nova zsk_* e atualize seu app.
Verifique logs de Events no dashboard por atividade suspeita nas últimas 24h.

Boas práticas

Use zrk_* em workers que NÃO precisam de write completo. 95% dos workers não precisam.
Multi-stage builds Docker — não inclua a key como ARG; injete em runtime.
Não use mesma zsk_live_* em múltiplos serviços. Crie uma por serviço — se um vazar, você sabe qual e isola.
Logs sanitizados. Configure seu logger (Pino, Winston) para mascarar Authorization headers automaticamente.
Deploy preview / staging usa *_test_*. Nunca live keys em ambiente não-prod.

Esta página foi útil?

Nesta página