Segurança

A autorização é feita apenas por chave

O contrato define exatamente dois esquemas de segurança, e ambos carregam o mesmo segredo:

Esquema	Cabeçalho	Observações
ApiKeyHeader	X-API-Key	Recomendado.
BearerAuth	Authorization: Bearer	Equivalente. Use-o quando uma biblioteca cliente exigir um bearer token.

Qualquer uma das formas resulta na mesma credencial. GET /v1/products é o único endpoint que aceita uma chamada não autenticada.

Não há lista de permissões de IP. O limite de requisições por IP é um teto compartilhado por tudo que está atrás de um mesmo endereço — ele limita o abuso, mas não concede nem nega acesso. Trate a chave como toda a fronteira de autoridade da sua conta.

A chave

Uma chave de API Zelnum é ck_ seguido de 48 caracteres: 51 no total. Qualquer coisa mais curta não é uma chave, o que é uma verificação útil quando um gerenciador de segredos corrompe um valor.

Faça	Não faça
Mantenha-a em um gerenciador de segredos ou em uma variável de ambiente	Coloque-a em um repositório, em um arquivo de configuração que os usuários possam ler ou em um log de CI
Envie-a do seu servidor	Coloque-a em JavaScript de navegador, em um pacote de aplicativo móvel ou em qualquer cliente público
Leia api_key_id quando precisar identificar a chave	Cole a própria chave em uma solicitação de suporte
Oculte-a nos logs	Registre cabeçalhos de requisição completos nos logs

Uma chave em um pacote de front-end não é um segredo. Se uma integração precisar chamar a API a partir de um navegador, o navegador deve chamar o seu próprio servidor, e o seu servidor deve guardar a chave — o teto por IP sobre o tráfego que parece não autenticado não vai salvá-lo.

O banco de dados armazena um hash SHA-256 e um prefixo de exibição de 9 caracteres, nunca o valor em si, então um dump vazado não entrega a ninguém um token utilizável. O outro lado disso é que nenhum endpoint pode devolver a sua chave: se você a perder, faça a rotação.

Confirme qual chave está ativa

curl -X GET "https://api.zelnum.com/api/v1/api-key" \
  -H "X-API-Key: YOUR_KEY_HERE"

A resposta traz api_key_id, masked_key, last_used e created_at — da chave ativa emitida mais recentemente na conta. O endpoint informa uma chave, então leia isso como “a chave que eu estaria usando agora”, e não como um inventário. Para ver todas as chaves, use o Console.

last_used é a forma mais rápida de confirmar que uma rotação teve efeito, com uma ressalva: ele é gravado no máximo uma vez a cada cinco minutos por chave, então uma chave que está sendo muito usada ainda pode aparecer como intocada por até cinco minutos depois que você muda para ela. Não conclua que uma implantação está quebrada apenas por um last_used desatualizado.

Rotação de uma chave

Uma conta pode manter várias chaves ativas ao mesmo tempo, e o Console as gerencia individualmente:

Ação no Console	Efeito
Criar	Adiciona uma chave. Toda chave existente continua funcionando.
Regenerar	Desativa essa chave e emite uma substituta com o mesmo nome. A original para de funcionar imediatamente.
Excluir	Remove uma chave de vez.

Isso lhe dá dois formatos de rotação, e a escolha depende de você poder ou não arcar com uma janela de sobreposição.

Criar uma segunda chave — a rotação gradual, e a preferível:

1. Crie a nova chave no Console. Nada mais muda; a chave antiga ainda autentica.
2. Prepare o novo valor em todos os lugares necessários — servidores de aplicação, workers, tarefas cron, scripts agendados — sem ativá-lo ainda.
3. Faça a virada das implantações. Verifique com GET /v1/api-key até que ele informe o novo api_key_id, considerando a granularidade de cinco minutos do last_used.
4. Exclua a chave antiga quando nada mais estiver chamando com ela. Esta é a etapa que de fato remove a credencial — uma rotação não está concluída enquanto ela não for feita.

Regenerar no mesmo lugar — quando o valor antigo precisa morrer agora:

Use isso quando uma chave foi exposta e qualquer validade contínua é um risco.

1. Aceite a lacuna. A chave antiga para de funcionar no instante em que você regenera, então todo componente que ainda a tiver retorna 401 unauthorized até ser reimplantado. Não há sobreposição, por design.
2. Regenere no Console e copie o valor em texto claro do banner imediatamente — ele é exibido ali e em nenhum outro lugar, nunca mais.
3. Implante o novo valor e então confirme que nada ainda está registrando 401.

O valor em texto claro é exibido uma única vez

O valor em texto claro de uma chave aparece apenas no momento em que ela é criada ou regenerada e nunca pode ser recuperado depois. Se você o perder antes de ele chegar ao seu armazenamento de segredos, faça a rotação novamente.

Transporte

Todo endpoint usa HTTPS. Não há listener em texto claro, e nenhum endpoint aceita downgrade, então não existe configuração em que uma chave trafegue sem criptografia.

Se você construir um proxy ou gateway na frente da API, encerre o TLS na borda e repasse o cabeçalho X-API-Key — não o reescreva e não o adicione aos logs de requisições de entrada.

O que você envia, e por quanto tempo isso é mantido

As entradas da API são números de telefone e endereços de e-mail — dados pessoais na maioria das jurisdições. Duas consequências:

• Envie apenas o que você precisa. Uma verificação exige o identificador e nada mais. Não adicione um id de usuário, uma referência interna ou metadados de texto livre ao corpo de uma requisição: isso não é armazenado como campo, apenas amplia a exposição dos seus próprios logs.
• Conheça as janelas de retenção. Os logs de tempo real e os resultados de repetição de idempotência são retidos por 30 dias por padrão, e os arquivos de resultado em lote por 7 dias (result_retention_days). Depois dessas janelas, os registros somem, então exporte tudo o que você for obrigado a manter.

Trate o número como sensível nos seus próprios sistemas também. Um resultado de detecção informa a um observador se uma pessoa específica está registrada em uma plataforma específica, e o par de identificador e veredito é mais revelador do que cada metade isolada.

Proteção contra cobrança dupla

Esta é uma propriedade de segurança tanto quanto de cobrança: Idempotency-Key torna uma nova tentativa segura, para que uma falha de rede ou um operador impaciente não transforme uma cobrança em duas. Nunca gere uma chave nova para repetir uma requisição cujo desfecho você não observou — consulte Idempotência e novas tentativas.

A seguir

• Status e suporte — o que incluir ao escalar, sem vazar a chave
• Códigos de erro — unauthorized e account_banned em contexto