JWT

1. Overview

The JWT component (jwt) creates, validates, encrypts, and decrypts JWT (JSON Web Token) tokens, used for authentication and secure information exchange between systems.

Use it when the flow needs to generate an access token, verify whether a received token is valid, or exchange encrypted information with another system. Don't use it as the end user's own login mechanism — this component only manipulates tokens, it doesn't manage sessions or users.

Works only as an output action within the flow — it can't be used as an entry trigger.

2. Prerequisites

• A key to sign/verify/encrypt/decrypt, which can be: a symmetric secret (secret), a key in JWK format (jwk), or a key in PEM format (pem), depending on the chosen algorithm.
• Knowledge of the desired cryptographic algorithm (e.g., HS256, RS256, RSA-OAEP-256).

3. Authentication and Connection

There's no connection to external systems — everything is processed locally. The "credential" here is the cryptographic key itself.

Field	Required	Type	Description	Example
secret	Depends on the algorithm	Text	Symmetric secret, used in HMAC algorithms (HS*) or symmetric-key encryption (A*KW).	"my-super-secret-secret"
jwk	Depends on the algorithm	Text (JSON)	Key in JWK (JSON Web Key) format. Alternative to secret/pem.	A JWK key JSON
pem	Depends on the algorithm	Text (PEM)	Key in PEM format, used in RSA/EC/OKP algorithms. Alternative to jwk.	A -----BEGIN... block

4. Configuration / Supported Operations

The mode field defines the operation performed.

Field	Required	Type	Description	Example
mode	No	Text: sign, verify, encrypt, or decrypt	Operation to run. Default value: "sign".	"verify"
algorithm	Depends on the mode	Text	Cryptographic algorithm. Required in encrypt. In the other modes, it must be provided correctly for the key to work.	"HS256", "RS256", "RSA-OAEP-256"

sign mode — sign a token

Field	Required	Type	Description	Example
claims	No	Text (JSON)	Data to include in the token's payload. Default value: "{}".	{"userId": 123}
ttlSeconds	No	Text (number)	Token's lifetime, in seconds. Default value: "3600" (1 hour).	"1800"

Response: {"token": "<signed jwt>"}.

verify mode — validate a token

Field	Required	Type	Description	Example
token	Yes	Text	The JWT to validate.	The token received from another system

Response: {"valid": true/false, "claims": {...} or null}.

encrypt mode — encrypt data into a JWE

Field	Required	Type	Description	Example
claims	No	Text (JSON)	Data to encrypt. Default value: "{}".	{"taxId": "123.456.789-00"}
ttlSeconds	No	Text (number)	Lifetime, in seconds. Default value: "3600".	"600"
encryptionMethod	No	Text	Content encryption method. Default value: "A256GCM".	"A128CBC-HS256"

Response: {"token": "<encrypted jwt>"}.

decrypt mode — decrypt a JWE

Field	Required	Type	Description	Example
token	Yes	Text	The encrypted JWT to decode.	The received token

Response: {"claims": {...}}.

5. Practical Examples

Simple example: generate an access token signed with a symmetric secret, valid for 30 minutes, containing the user's ID.

Input:

{
  "user": { "id": 123, "name": "Maria Silva" }
}

Component configuration:

{
  "componentName": "jwt",
  "configurations": {
    "mode": "sign",
    "algorithm": "HS256",
    "secret": "{$.secrets.jwtSecret}",
    "claims": "{\"userId\": {$.body.user.id}}",
    "ttlSeconds": "1800"
  }
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEyM30.signature..."
}

Advanced example: validate a token received in a request, to decide (with a Choice right after) whether the request can continue.

Input:

{
  "authorizationToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEyM30.signature..."
}

Component configuration:

{
  "componentName": "jwt",
  "configurations": {
    "mode": "verify",
    "algorithm": "HS256",
    "secret": "{$.secrets.jwtSecret}",
    "token": "{$.body.authorizationToken}"
  }
}

Response (valid token):

{
  "valid": true,
  "claims": { "userId": 123 }
}

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
"IN not supported for JWT connector"	Attempt to use JWT as an entry trigger.	Use the component only as an output action in the flow.
"Invalid mode: [value]"	The mode field isn't sign, verify, encrypt, or decrypt.	Fix the mode value.
"Token is required"	The verify/decrypt modes were used without filling in token.	Fill in token with the JWT to validate/decode.
"Algorithm is required for encryption"	The encrypt mode was used without filling in algorithm.	Provide the encryption algorithm (e.g., RSA-OAEP-256, A256KW).
"JWT processing error: ..."	Failure processing the token (key incompatible with the algorithm, expired or corrupted token).	Check whether the key (secret/jwk/pem) is compatible with the chosen algorithm.
"...requires 'secret' or JWK with 'oct' key type."	HMAC/symmetric algorithm (HS*, A*KW) without secret or a jwk of type oct.	Fill in secret or use a jwk of the correct type.
"Algorithm [alg] requires JWK or PEM key."	Asymmetric algorithm (RS*, ES*, RSA*) without jwk or pem.	Fill in jwk or pem with the corresponding key.