API Key

Para que serve uma API Key?

A API Key serve para responder a duas perguntas sempre que um sistema conversa com uma API: quem está fazendo o pedido e se ele tem permissão para isso. Sem essa identificação, qualquer pessoa que descobrisse o endereço da API poderia usá-la.

Em uma API fiscal, isso é ainda mais importante. A chave impede que terceiros emitam, cancelem ou baixem notas fiscais em nome da sua empresa. Ela também permite que o provedor saiba qual conta está consumindo o serviço, aplique os limites do plano e registre as operações realizadas.

Como funciona uma API Key na prática?

O fluxo costuma ser simples. Primeiro, a chave é gerada em um painel de gestão, como um console do provedor. Depois, o desenvolvedor configura essa chave no sistema da empresa, por exemplo, no ERP ou na plataforma de vendas.

A partir daí, toda requisição enviada à API leva a chave junto, normalmente em um cabeçalho HTTP indicado na documentação. O servidor confere se a chave existe, se está ativa e se tem permissão para aquela ação. Se estiver tudo certo, o pedido é processado; caso contrário, a API devolve um erro de autenticação ou de acesso negado.

Por exemplo: quando o ERP envia os dados de uma venda para gerar uma NF-e, a API Key garante que aquele pedido realmente veio do sistema autorizado da empresa.

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

A API Key é uma credencial fixa, que continua válida até ser revogada ou substituída. Ela identifica o sistema ou a conta que está acessando a API.

O Bearer token é um formato de envio de credencial: quem apresenta (em inglês, bearer, o portador) o token recebe acesso. Muitas vezes ele é temporário, gerado a partir de um login ou de outra credencial, e expira depois de algum tempo. Em algumas APIs, a própria API Key é enviada no formato de Bearer token, por isso os dois termos às vezes aparecem juntos.

Por que existem chaves diferentes para homologação e produção?

Muitas APIs fiscais separam o ambiente de testes, chamado de homologação, do ambiente real, chamado de produção. Em homologação, os documentos emitidos não têm valor fiscal; em produção, cada nota autorizada passa a valer perante o Fisco.

Ter chaves diferentes para cada ambiente evita acidentes, como emitir uma nota real durante um teste ou tentar validar uma integração usando dados de produção. Antes de colocar a integração no ar, vale conferir se o sistema está usando a chave do ambiente correto.

Como guardar uma API Key com segurança?

A API Key deve ser tratada como uma senha. Ela não deve aparecer no código de aplicativos ou sites que rodam no navegador do usuário, não deve ser enviada por e-mail ou chat e não deve ser salva em repositórios de código. O ideal é guardá-la em variáveis de ambiente ou em um cofre de segredos no servidor.

Outras boas práticas são criar chaves separadas para cada sistema ou integração, dar a cada uma apenas as permissões necessárias e trocar a chave periodicamente. Se houver suspeita de vazamento, a chave deve ser revogada imediatamente e substituída por uma nova.

API Keys também são usadas por agentes de inteligência artificial?

Sim. Quando um agente de IA acessa uma plataforma por meio de MCP (Model Context Protocol), ele também precisa de uma credencial para provar que está autorizado. Nesse caso, é especialmente importante limitar o que a chave permite fazer, por exemplo, liberar apenas consultas de documentos ou apenas ações específicas, e manter registro das operações para auditoria.

Exemplos de API Key

• Uma software house gera uma API Key no console do provedor fiscal e a configura no servidor do seu ERP, permitindo que o sistema emita NF-e automaticamente a cada pedido faturado.
• Um marketplace usa uma API Key de homologação para testar a emissão de NFS-e e, depois de validar os resultados, troca para a chave de produção.
• Após um desenvolvedor publicar por engano uma API Key em um repositório público, a equipe revoga a chave no painel e cria uma nova, evitando o uso indevido da conta.
• Uma empresa cria uma chave com permissão apenas de leitura para que um agente de IA consulte o status de notas fiscais sem poder emitir ou cancelar documentos.