Authenticate API endpoints using JWT in Jitterbit Studio

Introduction

API Manager endpoints accept requests from any caller that knows the URL. To restrict access, you can require callers to authenticate with a signed JSON Web Token (JWT): a compact, URL-safe token that encodes the caller's identity and an expiry time.

This guide covers the full authentication cycle using the JWT connector:

A login operation accepts a caller identity, generates a signed JWT, and returns it to the caller.
Protected operations validate the token on each request before processing begins.

The JWT connector handles token generation and validation locally. It does not connect to any external service.

This guide assumes the following:

A custom API is configured and published in API Manager in the same environment as the project.
You are familiar with creating custom API endpoints in API Manager.

Part 1: Create the JWT connection

A JWT connection is a named endpoint that gives you access to the Generate Token, Decode Token, and Validate Token activity types.

In Studio, open the design component palette and select the Project endpoints and connectors tab.
Locate the JWT connector and configure a new connection.
Connection name: Enter a name (for example, JWT).
Click Save Changes.

The JWT endpoint appears in the Project endpoints and connectors tab. For more information, see JWT connection.

Part 2: Create the login endpoint

The login endpoint accepts a POST request and returns a signed JWT. Callers present this token in the Authorization header of all subsequent requests to protected endpoints.

Step 1: Store the signing secret

Both the Generate Token and Validate Token activities use the same signing secret. Store it as a project variable so its value is not hardcoded and does not appear in operation logs. For the full steps and best practices for managing credentials as hidden project variables, see Manage endpoint credentials.

In Studio, open the project actions menu and select Project Variables.
Add a variable named jwt.secret and enter a strong, randomly generated string as its value.
Enable Hide value.
Click Save.

Step 2: Configure the Generate Token activity

In the design component palette, expand the JWT endpoint and drag the Generate Token activity type onto the design canvas.
Name: Enter a name (for example, Generate Login Token).
JWT type: Select JWS.
Signature type: Select Symmetric.
Signature algorithms: Select HS256.
Secret key: Enter [jwt.secret].
Expand Optional settings and add the following Payload Properties. These reference project variables that the login operation script sets at runtime:

Key Value Data Type

sub [jwt.sub] string

iat [jwt.iat] number

exp [jwt.exp] number
Click Finished.

For descriptions of all activity settings, see JWT Generate Token activity.

In API Manager, click New API and select Custom API.
Enter an API Name (for example, Auth API), a URL Prefix (for example, auth), and a Version string.
Enable SSL.
Click Save, then click Add Service.
Method: Select POST.
Path: Enter /token.
Operation: Select the login operation. If the operation does not exist yet, create a placeholder and return to update this field after completing Step 4.
Response Type: Select Variable.
Click Save, then click Publish.

The login operation consists of a preparation script and a transformation that runs the Generate Token activity.

Create the project variables for token claims by adding them in the Project Variables drawer alongside jwt.secret:

Name Description

jwt.sub The caller identity (subject claim)

jwt.iat Issue time as a Unix epoch timestamp

jwt.exp Expiry time as a Unix epoch timestamp
Add a preparation script as the first step of the login operation. This script reads the caller's identity from the request body and sets the claim project variables:
```
<trans>
$body = JSONParser($jitterbit.api.request.body);

// Set the subject claim from the request body
$jwt.sub = Get($body, "userId");

// Set the issue time and expiry as Unix epoch timestamps
// (seconds since 1970-01-01 00:00:00 UTC)
$jwt.iat = Long(Now());
$jwt.exp = $jwt.iat + 3600;  // 1-hour token lifetime
</trans>
```
Long(Now()) converts the current date-time to a Unix epoch integer (seconds since 1970-01-01 00:00:00 UTC). Adjust the expiry offset (3600) to suit the token lifetime required by your security policy.
Add a transformation step after the preparation script, with the Generate Token activity as its target. In the transformation, map each claim project variable to the corresponding payload schema node. The Generate Token activity reads the claim values from [jwt.sub], [jwt.iat], and [jwt.exp], and writes the signed JWT to its output schema.
Set the API response by adding a second transformation (using the two-transformation operation pattern) to map the generated token from the activity's output to $jitterbit.api.response. The Generate Token activity writes the signed JWT to its output data schema, shown in Step 2: Review the data schemas of the activity configuration:
```
<trans>
$token_response = Dict();
$token_response["token"] = $jwt_generated_token;
$jitterbit.api.response = JSONStringify($token_response);
$jitterbit.api.response.status_code = 200;
</trans>
```
Replace $jwt_generated_token with the variable or path that maps from the Generate Token activity's output schema. The exact field name is shown in the data schema review step of the activity configuration.

Part 3: Validate the token on protected endpoints

Each protected operation must verify the caller's JWT before processing the request. Add a validation operation that runs before the protected operation and returns a 401 response if the token is missing or invalid.

Step 1: Configure the Validate Token activity

In the design component palette, expand the JWT endpoint and drag the Validate Token activity type onto the design canvas.
Name: Enter a name (for example, Validate Login Token).
JWT token: Enter [jwt.incoming_token]. This references a project variable that the validation script sets from the Authorization header.
JWT type: Select JWS.
Secret key: Enter [jwt.secret].
Click Finished.

For descriptions of all activity settings, see JWT Validate Token activity.

Add a project variable named jwt.incoming_token in the Project Variables drawer.

Step 2: Build the validation operation

Create a new script operation to act as the gateway for your protected endpoint. This operation extracts the token, runs the Validate Token activity, and passes control to the protected operation if validation succeeds.

Add an extraction script as the first step of the validation operation. This script reads the Authorization header, checks for the Bearer prefix, and sets jwt.incoming_token:

<trans>
$auth_header = $jitterbit.api.request.headers.Authorization;

If(Left($auth_header, 7) != "Bearer ",
  $jitterbit.api.response.status_code = 401;
  $err_response = Dict();
  $err_response["error"] = "Missing or malformed Authorization header";
  $jitterbit.api.response = JSONStringify($err_response);
  RaiseError("Unauthorized");
);

$jwt.incoming_token = Mid($auth_header, 8);
</trans>

Left checks the first seven characters of the header. Mid extracts everything after the Bearer prefix. RaiseError stops the operation immediately and triggers the configured error action.

Add a validation transformation with the Validate Token activity as its target. The activity reads the token from [jwt.incoming_token] and verifies its signature against [jwt.secret]. If the token is invalid, expired, or has been tampered with, the activity raises an error.

Step 3: Configure error and success actions on the validation operation

Open the validation operation settings and select the Actions tab.

On failure (invalid token):

Condition: Select On Fail.
Action: Select Run Operation.

Operation: Select or create a script operation that returns a 401 response:

<trans>
$jitterbit.api.response.status_code = 401;
$err_response = Dict();
$err_response["error"] = "Invalid or expired token";
$jitterbit.api.response = JSONStringify($err_response);
</trans>

Click Add Action.

On success (valid token):

Condition: Select On Success.
Action: Select Run Operation.
Operation: Select the protected operation.
Click Add Action.

Save the settings. The validation operation now acts as a gateway: if the token is valid, it chains to the protected operation; if it is invalid or missing, it returns 401 and stops.

In API Manager, update the protected endpoint's Operation field to point to the validation operation instead of the protected operation directly. The validation operation chains to the protected operation on success.

Verify the integration

Deploy the project and confirm both the login endpoint and the protected endpoint are published in API Manager.
Send a POST request to the /auth/token endpoint with a JSON body containing a userId field:
```
{"userId": "user123"}
```
Confirm that the response body contains a token field.
Send a request to the protected endpoint with the token in the Authorization header:
```
Authorization: Bearer <token>
```
Confirm that the operation completes successfully.
Send a request to the protected endpoint without an Authorization header. Confirm that the endpoint returns a 401 response.
Modify the token string (for example, change the last character) and send it. Confirm that the endpoint returns a 401 response.
If any step fails, open the operation logs in Studio to check for errors.

Key	Value	Data Type
`sub`	`[jwt.sub]`	`string`
`iat`	`[jwt.iat]`	`number`
`exp`	`[jwt.exp]`	`number`

Name	Description
`jwt.sub`	The caller identity (subject claim)
`jwt.iat`	Issue time as a Unix epoch timestamp
`jwt.exp`	Expiry time as a Unix epoch timestamp