> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/integracao/jwt.md). # 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**.

Imagem 1 - Visão geral do módulo JWT no canvas do fluxo, mostrando as saídas de Sucesso e Erro no Hyperflow Integrações.

*** ## 🗺️ 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.

Imagem 2 - 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.

Imagem 3 - 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.

Imagem 4 - 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. {% hint style="warning" %} 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**. {% endhint %} Você pode usar uma variável do fluxo neste campo digitando `{{nome_da_variavel}}`.

Imagem 5 - 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:

Imagem 6 - 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 | {% hint style="info" %} Para a maioria dos casos, **HS256** é uma escolha segura e amplamente suportada. Use algoritmos RSA ou ECDSA quando precisar de chaves públicas/privadas. {% endhint %}

Imagem 7 - 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: ```json { "userId": "{{usuario_id}}", "role": "admin" } ``` Você pode usar variáveis do fluxo dentro do JSON. O conteúdo digitado aqui ficará acessível para quem verificar o token.

Imagem 8 - 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:

Imagem 9 - 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. ``` {{token_recebido}} ``` #### 🎯 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**.

Imagem 10 - 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. *** ## 📋 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**.