JWT

Para que serve o JWT?

O JWT serve principalmente para provar identidade e permissões em comunicações entre sistemas. Em vez de enviar usuário e senha a cada requisição, o sistema recebe um token assinado e o apresenta sempre que precisa acessar um recurso protegido.

Em integrações com APIs fiscais, por exemplo, um ERP ou uma plataforma de vendas pode usar um JWT para mostrar à API que está autorizado a emitir uma NF-e, consultar o status de uma NFS-e ou baixar o XML de um documento. O servidor confere o token e decide se libera ou bloqueia a operação.

Como funciona um JWT?

Um JWT é uma sequência de texto dividida em três partes separadas por pontos. A primeira é o cabeçalho, que indica o tipo do token e o algoritmo de assinatura. A segunda é o conteúdo, chamado de payload, que traz informações conhecidas como claims, por exemplo quem emitiu o token, para quem ele foi emitido e quando expira. A terceira é a assinatura.

Cabeçalho e conteúdo são escritos em formato JSON e depois codificados em Base64URL, um tipo de codificação que transforma os dados em texto seguro para trafegar na internet. A assinatura é calculada a partir dessas duas partes com uma chave secreta ou um par de chaves. Se alguém alterar qualquer letra do conteúdo, a assinatura deixa de bater e o servidor rejeita o token.

Algumas claims comuns são exp (data de expiração), iat (momento de emissão), iss (quem emitiu) e sub (a quem o token se refere). O padrão é aberto e descrito na RFC 7519.

O conteúdo de um JWT é secreto?

Na forma mais comum, não. O JWT assinado, tecnicamente chamado de JWS, garante que o conteúdo não foi alterado, mas não o esconde. Qualquer pessoa que tenha o token consegue decodificar o cabeçalho e o payload e ler o que está escrito.

Por isso, não se deve colocar em um JWT dados sensíveis, como senhas, conteúdo de certificados digitais ou informações fiscais confidenciais. Quando é preciso esconder o conteúdo, existe a variante criptografada, chamada JWE.

Qual a diferença entre JWT e API Key?

Uma API Key costuma ser uma sequência aleatória que funciona como uma senha fixa: o servidor precisa consultar sua base de dados para saber a quem ela pertence e quais permissões tem. Ela geralmente vale até ser revogada.

Já o JWT carrega dentro de si as informações necessárias, como identificação e validade, e o servidor consegue verificar a autenticidade apenas conferindo a assinatura. Em geral, JWTs têm vida curta e são renovados com frequência. Muitas APIs combinam os dois: a API Key ou credencial é usada para obter um JWT temporário, que então autentica as chamadas.

Como o JWT é enviado em uma requisição?

O jeito mais comum é colocar o token no cabeçalho HTTP Authorization, no formato Bearer, seguido do token. Por isso o JWT é frequentemente usado como bearer token, ou seja, quem o apresenta é tratado como portador da autorização.

Esse modelo aparece em fluxos de OAuth 2.0, em que um servidor de autorização gera o token de acesso, e também em cenários com agentes de inteligência artificial que acessam ferramentas via MCP, onde o token ajuda a limitar quais ações o agente pode executar.

Quais cuidados de segurança o JWT exige?

Como quem tem o token pode usá-lo, ele deve trafegar sempre por HTTPS e ser guardado em local protegido, nunca em logs, código-fonte ou repositórios públicos. Definir um tempo de expiração curto reduz o estrago caso o token vaze.

O servidor deve sempre validar a assinatura, o algoritmo esperado e a data de expiração, recusando tokens sem assinatura. Também vale lembrar que um JWT emitido continua válido até expirar, então revogá-lo antes disso exige mecanismos extras, como listas de bloqueio ou rotação de chaves.

Exemplos de JWT

• Um ERP envia sua credencial a um endpoint de autenticação, recebe um JWT válido por uma hora e o inclui no cabeçalho Authorization: Bearer de cada chamada para emitir NF-e.
• Uma plataforma de marketplace recebe erro 401 ao consultar o status de uma NFC-e porque o JWT expirou; o sistema então solicita um novo token e repete a consulta.
• Um agente de inteligência artificial conectado via MCP recebe um token com permissão apenas de leitura, podendo consultar documentos fiscais, mas não cancelá-los.
• Durante a depuração, um desenvolvedor decodifica o payload do JWT e confirma que a claim exp indica um horário já passado, explicando a rejeição das requisições.