Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

JWT

O módulo JWT permite que você gere ou valide tokens de autenticação no padrão JSON Web Token diretamente dentro de um fluxo. Com ele, é possível criar tokens seguros para identificar usuários ou sistemas, e também verificar se um token recebido é válido antes de permitir a continuidade do fluxo.

Ao final da execução, o módulo retorna um de dois caminhos: Sucesso ou Erro.

📷 Inserir print: visão geral do módulo JWT no canvas do fluxo, mostrando as saídas de Sucesso e Erro

🗺️ Como acessar

  1. No menu lateral, clique em Gerenciamento de aplicativos.

  2. Selecione Fluxos.

  3. Abra o fluxo desejado ou crie um novo.

  4. No painel de módulos, localize JWT na categoria de integrações e arraste-o para o canvas.

📷 Inserir print: painel lateral de módulos com JWT visível na listagem de integrações

🧩 Conhecendo o módulo

Ao clicar no módulo JWT dentro do fluxo, um painel de configuração é aberto à direita. As opções disponíveis mudam conforme o Tipo selecionado.

📷 Inserir print: painel de configuração do módulo JWT aberto, com os campos visíveis

1️⃣ Tipo

O primeiro campo a preencher é o Tipo, que define o que o módulo vai fazer:

Valor
O que faz

SIGN

Cria e assina um novo token JWT com os dados que você informar

VERIFY

Valida um token JWT existente e retorna os dados contidos nele

Selecione o tipo antes de preencher os demais campos, pois as opções disponíveis mudam conforme a escolha.

📷 Inserir print: campo Tipo com as opções SIGN e VERIFY no seletor

2️⃣ Chave secreta (Secret)

Campo obrigatório para os dois tipos. É a chave usada para assinar (no modo SIGN) ou validar (no modo VERIFY) o token.

A chave secreta deve ser a mesma nos dois lados: quem gera o token e quem verifica. Se as chaves forem diferentes, a verificação falhará e o fluxo seguirá pelo caminho de Erro.

Você pode usar uma variável do fluxo neste campo digitando {{nome_da_variavel}}.

📷 Inserir print: campo Secret preenchido com uma variável de fluxo

✍️ Configurações do tipo SIGN

Quando o tipo SIGN está selecionado, três campos adicionais aparecem:

📷 Inserir print: painel com os campos de SIGN visíveis: Expires in, Algorithm e Body

⏱️ Validade (Expires in)

Define por quanto tempo o token será válido. Use o formato abreviado:

  • 1h = 1 hora

  • 7d = 7 dias

  • 30m = 30 minutos

Deixar este campo vazio cria um token sem prazo de expiração.

🔒 Algoritmo (Algorithm)

Escolha o algoritmo criptográfico usado para assinar o token. As opções disponíveis são:

Família
Algoritmos

HMAC (chave simétrica)

HS256, HS384, HS512

RSA (chave assimétrica)

RS256, RS384, RS512

RSA-PSS

PS256, PS384, PS512

ECDSA

ES256, ES384, ES512

Para a maioria dos casos, HS256 é uma escolha segura e amplamente suportada. Use algoritmos RSA ou ECDSA quando precisar de chaves públicas/privadas.

📷 Inserir print: seletor de Algorithm com as opções listadas

📦 Corpo do token (Body)

Campo onde você define os dados que serão embutidos no token. Deve ser preenchido no formato JSON:

Você pode usar variáveis do fluxo dentro do JSON. O conteúdo digitado aqui ficará acessível para quem verificar o token.

📷 Inserir print: editor de Body com um JSON de exemplo preenchido

🎯 Propósito

Criar um token JWT assinado com os dados do usuário ou da sessão, para ser usado em chamadas autenticadas ou passado adiante no fluxo.

✅ Como fazer na tela

  1. Selecione o Tipo como SIGN.

  2. Preencha a Chave secreta.

  3. Informe a Validade (ex: 1h).

  4. Escolha o Algoritmo (ex: HS256).

  5. Preencha o Corpo do token com os dados em JSON.

  6. Conecte a saída Sucesso ao próximo passo do fluxo. O token gerado estará disponível como variável para uso nos módulos seguintes.

📌 Resultado esperado

O módulo gera o token JWT e envia o resultado pelo caminho de Sucesso. O token estará disponível como uma variável para uso nos próximos módulos do fluxo.

🔍 Configurações do tipo VERIFY

Quando o tipo VERIFY está selecionado, um campo adicional aparece:

📷 Inserir print: painel com o campo JWT Token visível no modo VERIFY

🎫 Token JWT (JWT Token)

Informe o token que você deseja verificar. Normalmente, este campo recebe uma variável que carrega o token vindo de uma requisição externa ou de um módulo anterior no fluxo.

🎯 Propósito

Validar se um token JWT recebido é legítimo e extrair os dados contidos nele para uso no fluxo.

✅ Como fazer na tela

  1. Selecione o Tipo como VERIFY.

  2. Preencha a Chave secreta — deve ser a mesma usada na criação do token.

  3. No campo Token JWT, insira o token a ser verificado (use uma variável, ex: {{token}}).

  4. Conecte a saída Sucesso ao caminho que deve seguir quando o token for válido.

  5. Conecte a saída Erro ao caminho que deve seguir quando o token for inválido ou expirado.

📌 Resultado esperado

Se o token for válido, o módulo segue pelo caminho de Sucesso e os dados do token ficam disponíveis como variável. Se o token for inválido, expirado ou assinado com uma chave diferente, o fluxo segue pelo caminho de Erro.

📷 Inserir print: fluxo mostrando as duas saídas do módulo JWT (Sucesso e Erro) conectadas a módulos diferentes

💡 Dicas úteis

  • Variáveis em todos os campos: os campos Chave secreta, Validade e Token JWT aceitam variáveis do fluxo no formato {{nome_da_variavel}}. Use-as para tornar o módulo dinâmico.

  • Algoritmos simétricos vs. assimétricos: algoritmos da família HMAC (HS256, HS384, HS512) usam uma única chave secreta compartilhada. Algoritmos RSA e ECDSA usam par de chave pública/privada — mais seguros para cenários de múltiplos serviços.

  • Token expirado = caminho de Erro: se o token ainda é válido estruturalmente mas já passou do prazo de validade, o módulo VERIFY também roteia para o caminho de Erro.

  • Sem expiration: no modo SIGN, deixar o campo Validade vazio cria um token que nunca expira — use com cautela em contextos de segurança.

🧪 Caso de uso

Autenticação de acesso a conteúdo protegido

Uma empresa quer garantir que apenas usuários autenticados consigam avançar em um fluxo de atendimento e acessar informações sensíveis.

Configuração principal:

  1. No início do fluxo, um módulo Chat coleta o identificador do usuário (ex: CPF ou e-mail).

  2. Um módulo JWT com tipo SIGN gera um token com os dados do usuário:

    • Corpo: {"userId": "{{cpf}}", "role": "cliente"}

    • Validade: 2h

    • Algoritmo: HS256

  3. O token gerado é armazenado em uma variável e repassado às próximas etapas do fluxo.

  4. Mais adiante, antes de exibir dados protegidos, outro módulo JWT com tipo VERIFY valida o token:

    • Se Sucesso: o fluxo continua e exibe as informações.

    • Se Erro: o fluxo encerra com uma mensagem de acesso negado.

Resultado esperado: apenas usuários com token válido e dentro do prazo de 2 horas conseguem acessar as informações protegidas, garantindo segurança e rastreabilidade no atendimento.

📷 Inserir print: fluxo completo mostrando os dois módulos JWT (SIGN e VERIFY) em sequência, com os caminhos de Sucesso e Erro do VERIFY conectados

📋 Resumo

  • O módulo JWT opera em dois modos: SIGN (gera token) e VERIFY (valida token).

  • No modo SIGN, configure: chave secreta, validade, algoritmo e corpo do token em JSON.

  • No modo VERIFY, informe a chave secreta e o token a validar — o resultado chega pelo caminho de Sucesso ou Erro.

  • Todos os campos aceitam variáveis do fluxo no formato {{variavel}}.

  • Tokens expirados ou com chave incorreta sempre resultam no caminho de Erro.