# Header de autenticação > Header de autenticação é um campo enviado no cabeçalho de cada requisição HTTP que identifica quem está chamando uma API e comprova que essa chamada tem permissão. Em uma API fiscal, ele carrega uma credencial, como API Key ou Bearer token, para que apenas sistemas autorizados emitam, consultem ou cancelem documentos fiscais. **Também conhecido como:** Cabeçalho de autenticação, Header Authorization, Cabeçalho Authorization, Authorization header, Authentication header **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** H ## O que é um header de autenticação, na prática? Toda requisição HTTP é formada por algumas partes: o endereço (endpoint), o método (como GET ou POST), o corpo com os dados e os headers, que são linhas de informação extra enviadas junto com o pedido. Os headers funcionam como a etiqueta de um envelope: não são o conteúdo da carta, mas dizem ao destinatário como tratá-la. O header de autenticação é uma dessas etiquetas. Ele leva uma credencial secreta que permite à API reconhecer quem está fazendo o pedido. Sem ele, a API não sabe se a requisição veio de um cliente legítimo ou de alguém desconhecido, e por isso costuma recusá-la. ## Como funciona o header de autenticação em uma API fiscal? Quando um ERP, uma plataforma de vendas ou um marketplace quer emitir uma NF-e, uma NFS-e ou uma NFC-e por API, ele monta a requisição com os dados do documento e inclui o header de autenticação com a credencial fornecida pelo provedor. A API lê esse header antes de qualquer outra coisa. Se a credencial for válida, a API verifica quais permissões ela tem e a qual conta ou empresa está vinculada, e só então processa a emissão. Se for inválida, ausente ou expirada, a requisição é interrompida ali mesmo, sem que nenhum documento seja criado. Esse controle é especialmente importante em ambientes com várias empresas emissoras, pois garante que um sistema só acesse os documentos e CNPJs da conta à qual pertence. ## Quais são os formatos mais comuns de header de autenticação? O formato mais difundido usa o header padrão Authorization, seguido de um esquema e da credencial. No esquema Bearer, por exemplo, a linha fica parecida com Authorization: Bearer seguido do token. Esse modelo é muito usado com tokens gerados por OAuth 2.0 ou com JWT. Outro formato frequente é um header personalizado dedicado à chave de API, algo como X-API-Key seguido do valor da chave. Há ainda o esquema Basic, que envia usuário e senha codificados em Base64, hoje menos recomendado para integrações entre sistemas. O nome exato do header e o formato aceito sempre devem ser conferidos na documentação de cada API. ## Qual a diferença entre header de autenticação e certificado digital? São coisas diferentes, que muitas vezes aparecem juntas na emissão fiscal. O header de autenticação prova à API do provedor que o seu sistema pode usar o serviço. O certificado digital, como o A1, identifica a empresa emissora perante a SEFAZ ou a prefeitura e é usado para assinar o XML do documento. Em uma integração por API fiscal, o sistema do cliente normalmente só envia o header de autenticação em cada chamada. O certificado fica cadastrado no provedor, que o utiliza para assinar e transmitir os documentos aos órgãos autorizadores. ## Quais cuidados de segurança o header de autenticação exige? A credencial do header equivale a uma senha: quem a possui pode agir em nome da sua empresa. Por isso, ela deve trafegar apenas por HTTPS, que criptografa a comunicação, e nunca ser colocada em query string, pois endereços costumam ficar gravados em históricos e logs. Também é recomendável guardar a credencial em um cofre de segredos ou variável de ambiente, e não diretamente no código-fonte; evitar que ela apareça em logs de integração; usar credenciais separadas para homologação e produção; e trocá-la periodicamente ou sempre que houver suspeita de vazamento. ## Que erros costumam aparecer quando o header está errado? O mais comum é o código HTTP 401 (Unauthorized), que indica credencial ausente, inválida ou expirada. Ele aparece quando o header não foi enviado, foi escrito com nome errado, falta o prefixo esperado (como Bearer) ou a chave tem espaços e caracteres a mais. Já o código 403 (Forbidden) indica que a credencial foi reconhecida, mas não tem permissão para aquela ação, como cancelar um documento ou acessar dados de outra empresa. Diferenciar os dois ajuda a resolver o problema mais rápido. ## Exemplos de Header de autenticação - Um ERP envia uma requisição POST para emitir uma NF-e e inclui o header Authorization: Bearer seguido do token da conta; a API valida o token e devolve o status da emissão. - Uma plataforma de agendamento emite NFS-e para vários prestadores e usa uma chave de API diferente em cada ambiente, enviando no header a chave de homologação durante os testes e a de produção após a publicação. - Um desenvolvedor recebe erro 401 ao consultar o status de uma NFC-e e descobre que havia copiado a chave com um espaço no final, o que invalidava o header. - Um agente de inteligência artificial conectado via MCP consulta documentos fiscais usando uma credencial com permissão apenas de leitura, de modo que tentativas de cancelamento são recusadas. ## Perguntas frequentes ### Preciso enviar o header de autenticação em todas as requisições? Sim, na maioria das APIs REST. Elas não guardam sessão entre chamadas, então cada requisição precisa trazer sua própria credencial para ser aceita, inclusive consultas, downloads de XML e cancelamentos. ### Posso colocar a chave de API na URL em vez do header? Não é recomendado. URLs costumam ficar registradas em logs, históricos de navegador e ferramentas de monitoramento, aumentando o risco de vazamento. O header, enviado por HTTPS, é o local adequado para credenciais. ### O que fazer se a credencial do header vazar? Revogue ou substitua a credencial imediatamente no painel do provedor, atualize-a nos sistemas que a utilizam e revise os registros de acesso para identificar chamadas suspeitas feitas no período. ## Termos relacionados - [API Key](https://conota.dev/glossario/api-key.md) - [Bearer token](https://conota.dev/glossario/bearer-token.md) - [Token de autenticação](https://conota.dev/glossario/token-de-autenticacao.md) - [HTTPS](https://conota.dev/glossario/https.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [Permissão de acesso à API](https://conota.dev/glossario/permissao-de-acesso-a-api.md) --- Fonte: [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao/) · Atualizado em 2026-10-22