Chaves de API
Autenticação usa chaves estáticas com prefixo reconhecível e alta entropia. Cada chave é vinculada a uma loja específica.Formato
- Prefixo
hk_(fixo) - 43 caracteres base64url após o prefixo (não usa
+,/, ou=) - Total: ~46 caracteres
Como obter
Chaves são geradas pela equipe de admin da loja parceira (rota interna/admin/hunter/api-keys). Peça pelo canal combinado (email, WhatsApp, Slack).
Quando gerar, você receberá:
- A chave completa (uma única vez — a partir dali só o prefixo de 12 caracteres é visível)
- Nome descritivo (pra identificar em quais integrações a chave é usada)
- Data de criação
Como enviar
Header obrigatório em todo request:Segurança
O que a chave concede
Uma chave dá acesso a todos os endpoints da API, no escopo da loja onde foi gerada. Ela não segrega leitura de escrita nem endpoint por endpoint. Tratamento equivalente a credenciais de root: rotacione periodicamente e guarde no cofre.Revogação
Chaves comprometidas podem ser revogadas imediatamente pela equipe da loja. Um request feito com chave revogada recebe:HTTP 401.
Rotação recomendada
- Solicite geração de uma nova chave
- Distribua a nova chave nos sistemas produtivos
- Confirme que a antiga não é mais usada
- Peça revogação da antiga
Erros de autenticação
Requests que caem nesses casos não consomem rate limit (é validado antes).
Armazenamento local
Boas práticas pra guardar a chave no seu integrador:- Não commite em código versionado
- Use variável de ambiente ou cofre (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, etc)
- Em ambientes CI/CD, use secrets do provedor (GitHub Actions Secrets, GitLab Variables, etc)
- Log de request nunca deve gravar o valor da chave — só o prefixo (
hk_xxxxxxxx…) pra correlação