Usuário autorizado na API

O que significa ser um usuário autorizado na API?

Uma API é a porta pela qual um sistema conversa com outro. Para que essa porta não fique aberta a qualquer um, cada chamada precisa vir de alguém identificado e liberado. Esse alguém é o usuário autorizado.

Apesar do nome, o usuário nem sempre é uma pessoa. Pode ser um ERP, uma plataforma de vendas, um script interno ou um agente de inteligência artificial. O que importa é que ele tenha uma credencial válida, como uma API Key ou um token, e permissões compatíveis com a ação que tenta executar.

Qual a diferença entre autenticação e autorização?

Autenticação responde à pergunta "quem é você?". É o momento em que a API confere a credencial enviada, normalmente em um header de autenticação, e confirma a identidade de quem está chamando.

Autorização responde à pergunta "o que você pode fazer?". Mesmo um usuário autenticado pode ser impedido de cancelar uma nota ou de acessar dados de uma empresa que não é sua. Ser um usuário autorizado significa passar pelas duas etapas: estar identificado e ter permissão para aquela ação específica.

Como funciona a autorização em uma API fiscal?

Em uma API fiscal, as permissões costumam ser definidas por tipo de ação (emitir, consultar, cancelar, baixar XML), por tipo de documento (NF-e, NFS-e, NFC-e, CT-e, MDF-e) e por empresa emissora. Assim, um sistema de vendas pode emitir NFC-e de uma loja sem enxergar as notas de outra filial.

Quando um usuário tenta fazer algo fora do que lhe foi liberado, a API recusa a requisição, geralmente com uma resposta de acesso negado. Isso protege dados sensíveis, como valores de vendas e informações de clientes, e evita emissões ou cancelamentos indevidos.

Em plataformas que atendem vários CNPJs, a autorização também garante a segregação de dados por conta: cada usuário só acessa as empresas às quais está vinculado.

Agentes de IA podem ser usuários autorizados?

Sim. Com o MCP, um agente de inteligência artificial pode se conectar a uma infraestrutura fiscal para consultar documentos, verificar status ou executar ações. Nesse caso, o agente funciona como um usuário autorizado com permissões controladas.

A boa prática é dar ao agente apenas o necessário. Um assistente que responde dúvidas sobre notas emitidas, por exemplo, pode ter acesso somente de leitura, sem poder emitir ou cancelar. Todas as ações ficam registradas para auditoria, permitindo saber o que foi feito e por quem.

Qual a diferença para as pessoas autorizadas no XML da NF-e?

São conceitos diferentes que às vezes se confundem. A NF-e possui um campo próprio no leiaute para indicar CPFs ou CNPJs autorizados a obter o XML da nota junto à SEFAZ, como o escritório de contabilidade do emitente ou uma transportadora.

Já o usuário autorizado na API diz respeito ao acesso à plataforma de emissão: quem pode chamar os endpoints e o que pode fazer neles. Um contador pode constar como autorizado no XML de uma nota sem ter qualquer acesso à API da empresa, e vice-versa.

Quais cuidados ao gerenciar usuários autorizados?

O princípio mais importante é o do menor privilégio: cada usuário recebe só as permissões de que realmente precisa. Credenciais diferentes para cada sistema ou integração facilitam identificar a origem de um problema e revogar um acesso sem afetar os demais.

Também é recomendável guardar as credenciais em um cofre de segredos, nunca no código-fonte, fazer rotação periódica de chaves, separar credenciais de homologação e de produção e remover imediatamente acessos de sistemas desativados ou de pessoas que deixaram a empresa.

Exemplos de Usuário autorizado na API

• Um ERP recebe uma credencial com permissão para emitir e consultar NF-e de três CNPJs do mesmo grupo, mas sem permissão para cancelar notas, tarefa reservada ao time fiscal.
• Uma plataforma de agendamento de serviços é cadastrada como usuário autorizado apenas para emitir NFS-e e baixar o PDF e o XML dos documentos gerados.
• Um agente de IA conectado via MCP tem acesso somente de leitura para responder ao financeiro quais notas foram rejeitadas na última semana e qual o motivo.
• Após a troca de fornecedor de sistema de vendas, a empresa revoga a credencial antiga, impedindo que o sistema desativado continue chamando a API.