Proteger o segredo

O segredo da chave aparece somente na criação. Guarde-o num gerenciador de segredos ou variável de ambiente do servidor. Nunca o coloque no front-end, no repositório, em logs ou na URL. A API não aceita segredo na URL; envie o par por HTTP Basic.

Crie uma chave por integração para limitar o impacto de uma troca. Se houver suspeita de vazamento, revogue a chave imediatamente e substitua-a. Para trocas planejadas, rotacione: o par antigo segue válido por 24 horas enquanto você atualiza o servidor.

Permitir apenas os IPs do projeto

  1. Em Projetos, abra o projeto usado pela integração.
  2. Adicione à allowlist de IP todos os endereços públicos de saída de seus servidores.
  3. Teste uma chamada a partir do servidor antes de restringir o acesso de outros ambientes.

Com a lista ativa, uma chamada vinda de outro IP retorna 403 ip_not_allowed. Se seus IPs mudam, mantenha a lista atualizada antes de transferir a execução. A restrição pertence ao projeto, não à conta inteira.

Edição do projeto com o campo Allowlist de IP preenchido com um endereço de exemplo
Allowlist de IP no projeto do painel de teste. O endereço exibido é apenas um exemplo.

Vincular a chave ao projeto certo

Ao criar uma chave, escolha Conta inteira para uma integração que seleciona projetos com X-Project-Id, ou Somente o projeto quando ela deve operar em um projeto específico. A chave vinculada recusa outro projeto. Confira também o escopo: se a chave não alcança o serviço, a API responde 403.

Rotacionar sem interromper

Use Rotacionar em Chaves de API para gerar um novo par com o mesmo ambiente e restrições. Salve o novo segredo na hora e atualize todos os servidores dentro da janela de 24 horas em que o par antigo ainda autentica. Depois confirme as chamadas pelo log_id. Revogar é imediato e não tem volta.

Verificar a assinatura da resposta

Quando sua integração exige prova de origem e integridade, verifique a assinatura Ed25519 da resposta. Busque a chave pública publicada em /.well-known/api4devs-keys.json. O key_id indica qual chave foi usada e permite acompanhar a rotação das chaves públicas.

bash
curl 'https://staging.apifordevs.com/api/v1/.well-known/api4devs-keys.json'

Use o guia Assinatura da resposta para montar a verificação dos bytes exatos e dos headers. Não transforme o corpo antes de verificar, pois isso pode invalidar a assinatura.

Respostas rápidas

Não. A API não aceita segredo na URL. Envie o par por HTTP Basic, a partir do servidor.

Próximos passos

Chaves de API

Crie, guarde e rotacione credenciais.

Projetos

Separe limites e acesso.

Assinatura da resposta

Referência para verificar Ed25519.