X-API-Key

O que significa o nome X-API-Key?

O nome tem duas partes. API Key é a chave de API, um código longo e secreto que funciona como uma credencial de acesso para sistemas, não para pessoas. O prefixo X- é uma convenção antiga usada para indicar cabeçalhos personalizados, ou seja, que não fazem parte da lista oficial de cabeçalhos do protocolo HTTP.

Com o tempo, a comunidade que define padrões da web passou a desaconselhar o uso do prefixo X- em novos cabeçalhos. Mesmo assim, X-API-Key se popularizou tanto que continua sendo um dos nomes mais comuns para transportar chaves de API. Vale lembrar que nomes de cabeçalhos HTTP não diferenciam maiúsculas de minúsculas, então x-api-key e X-API-Key são tratados da mesma forma.

Como funciona o cabeçalho X-API-Key?

Toda requisição HTTP pode levar cabeçalhos, que são informações extras enviadas junto com o pedido. Quando um sistema chama uma API que usa esse padrão, ele inclui uma linha no formato X-API-Key: seguido do valor da chave. O servidor lê esse cabeçalho, verifica se a chave existe, se está ativa e quais permissões ela tem, e só então processa o pedido.

Em uma integração fiscal, isso acontece em cada chamada: ao enviar o payload de uma NF-e para emissão, ao consultar o status de uma NFS-e ou ao baixar o XML autorizado. A chave identifica a conta ou o ambiente de quem está fazendo a requisição, o que permite à plataforma saber a quais empresas emissoras aquele sistema tem acesso.

Para que serve o X-API-Key em uma API fiscal?

A principal função é autenticar a comunicação entre máquinas. Um ERP, um marketplace ou um software de gestão não tem uma pessoa digitando senha a cada nota emitida; ele precisa de uma credencial fixa que possa ser usada de forma automática e contínua. O X-API-Key cumpre esse papel de maneira simples.

Além de identificar quem chama, a chave costuma estar ligada a permissões e a um ambiente específico. É comum existir uma chave para o ambiente de homologação, usado em testes sem valor fiscal, e outra para o ambiente de produção, onde os documentos têm validade jurídica. Assim, um erro de configuração no teste não gera notas reais.

Qual a diferença entre X-API-Key e Bearer token?

Os dois são formas de enviar credenciais em cabeçalhos, mas seguem lógicas diferentes. O X-API-Key leva diretamente uma chave fixa, geralmente de longa duração, criada em um painel e usada até ser revogada ou trocada. O Bearer token é enviado no cabeçalho Authorization e costuma ser um token temporário, muitas vezes obtido por um fluxo como OAuth 2.0 e com prazo de expiração curto.

Na prática, o X-API-Key é mais simples de implementar e muito usado em integrações entre servidores. O Bearer token oferece mais controle em cenários com vários usuários e delegação de acesso. Algumas APIs aceitam apenas um dos modelos; a documentação do serviço define qual deve ser usado.

Como proteger uma chave enviada no X-API-Key?

Quem tem a chave consegue agir em nome da sua empresa, inclusive emitindo ou cancelando documentos fiscais. Por isso, ela deve ser tratada como uma senha. As requisições precisam usar sempre HTTPS, para que o cabeçalho trafegue criptografado, e a chave nunca deve ficar exposta em código de frontend, aplicativos instalados no celular do cliente ou repositórios públicos.

Boas práticas incluem guardar a chave em um cofre de segredos ou em variáveis de ambiente do servidor, usar chaves diferentes para cada ambiente e sistema, conceder apenas as permissões necessárias e fazer a rotação periódica, criando uma nova chave e desativando a antiga. Se houver suspeita de vazamento, a chave deve ser revogada imediatamente.

Exemplos de X-API-Key

• Um ERP envia uma requisição POST para o endpoint de emissão de NF-e com o cabeçalho X-API-Key contendo a chave de produção, e recebe de volta o identificador do documento para acompanhar a autorização.
• Uma plataforma de vendas on-line consulta periodicamente o status de várias NFC-e, incluindo em cada chamada o cabeçalho X-API-Key para provar que tem acesso àquelas empresas.
• Durante os testes de integração, a equipe de desenvolvimento usa uma chave de homologação no X-API-Key para emitir NFS-e sem valor fiscal e validar o fluxo antes de ir para produção.
• Após um desenvolvedor sair da empresa, o time de tecnologia gera uma nova chave, atualiza o valor do X-API-Key no servidor do ERP e revoga a chave antiga.