Proxy API configuration in Jitterbit API Manager

Introduction

This page describes how to create and configure a proxy API from the APIs page of Jitterbit API Manager. A proxy API is one of the three types of APIs configured through API Manager. For the two other types, custom API and OData service, see Custom API configuration and OData service configuration.

Alternatively, create proxy APIs using the APIM AI Assistant.

Prerequisites

Unlike a custom API or OData service, which exposes a Harmony operation for consumption, a proxy API is used with an existing API. Proxied APIs are not routed through Jitterbit agents. The gateway processing the API must be able to access the API being proxied:

• Cloud API gateway: If you use the cloud API gateway (hosted by Jitterbit), the existing API must be accessible publicly, even if secured. The API you are trying to proxy cannot be behind a firewall. To allowlist the cloud API gateway IP addresses to allow the gateway access to the API being proxied, see Allowlist information and navigate to https://services.jitterbit for your region.

• Private API gateway: If you use a private API gateway (hosted on a private network), the private API gateway must be able to access the existing API.

Even though each proxy API allows multiple services to be assigned to a unique URL, the base proxy URL consumes the entitlement.

Create a new proxy API

To create a new proxy API, click New and select one of the following options:

• Build with AI: Opens the APIM Assistant to create an API using natural language prompts. For more information, see Using the AI Assistant.

  Note

  To use the APIM AI Assistant, your Harmony license must include the APIM AI Assistant option. Contact your Customer Success Manager (CSM) to add this option to your license.

• Proxy API: Opens the proxy API configuration screen to manually create a new proxy API. This option is enabled only if a corresponding API URL is available.

Configure a proxy API

When you configure a proxy API manually, the configuration screen includes multiple tabs. The configuration screen includes three required tabs and three optional tabs:

• Profile tab (required)
• Settings tab (optional)
• Existing API tab (required)
• Services tab (required)
• Security profiles tab (optional)
• Request headers tab (optional)

Profile tab

Use the Profile tab to enter basic information that identifies the API.

Configure the following settings:

• API Name: Enter a name for the proxy API to use for internal identification purposes. The following special characters are allowed: ( ) - _.

• Service Root: The public name of the API to use as part of the API's service URL. By default, this field is populated with the Proxy Name converted to camel case. This field does not allow spaces or certain special characters. Using special characters other than an underscore (_) is not recommended. The following special characters are allowed: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

• Description: Enter an optional description for the API.

• Environment: Use the menu to select the environment where the API will reside. You can type any part of the environment name into the menu to filter the list of environments. The menu results are filtered in real time with each keystroke.

  Note

  After API creation, you cannot change the environment. To move an API between environments, you can clone the API or export and import the API in another environment.

• Version number: Enter an optional version to use as part of the API's service URL. This field allows a maximum of 48 characters and does not allow spaces or certain special characters. Using special characters other than a period (.) or a hyphen (-) is not recommended. Common naming conventions include incrementing versions such as v1.0, v1.1, v1.2, or using a date that the API was published such as 2025-08-28.

After you complete the Profile tab, click Next to proceed to the Settings tab, or click Save as draft to save your progress.

Settings tab

The Settings tab is optional and contains advanced configuration options for the API.

Configure the following settings as needed:

• Timeout: Enter the number of seconds before the API will time out. The default is 30 seconds. The maximum value allowed is 180 seconds.

  Note

  This setting is independent of the operation timeout setting in Studio or Design Studio. Operation timeout settings are not used unless the EnableAPITimeout setting in the private agent configuration file is enabled.

• SSL only: This toggle is enabled by default and requires HTTPS for the API. When enabled, data is encrypted through SSL and an HTTP request returns an error. When disabled, both HTTP and HTTPS requests are supported.

  Warning

  When disabled, data passed through API requests and responses is not encrypted and can be intercepted and viewed by others. This could potentially expose sensitive information.

• CORS: Enable this toggle to support CORS (Cross-Origin Resource Sharing). CORS is a mechanism that allows web applications running in a web browser on one domain to access resources from a server on a different domain.

  Warning

  Enabling CORS causes operations using the OPTIONS method to run without authentication.

• Verbose logging: Enable this toggle to add raw request and response data — including headers, parameters, and bodies — to the call log when an API request is made. This data appears in the API Logs page and the Management Console Runtime page for both successful and unsuccessful runs. Verbose logging does not generate Studio operation log entries for successful runs. To log successful operation runs in Studio, use Enable debug mode until instead.

  Warning

  Verbose logging may include sensitive data such as authentication credentials or personally identifiable information. Values for masked headers are hidden, but parameters and bodies are logged in full. Use this setting carefully.

• Enable debug mode until: Enable this toggle to turn on detailed logging for troubleshooting, then click the calendar icon to select a date up to two weeks from today when debug mode automatically turns off. When enabled, request and response data (kept for 30 days) appears in the API Logs page, the Management Console Runtime page, and Studio operation logs for both successful and unsuccessful runs. Activity-level debug logging is also enabled, capturing component input and output data in the Debug Logging tab. This setting overrides Verbose logging: when debug mode is enabled, request and response data is included in logs regardless of whether Verbose logging is enabled.

  Warning

  Debug logs contain all request and response data, including sensitive information such as passwords and personally identifiable information (PII). Apart from the values for masked headers, this data appears in clear text in Harmony cloud logs for 30 days.

• Show Request & Response Payloads in Logs: This toggle is visible in the proxy API settings but has no effect. Request and response payload logging is not supported for proxy APIs.

After you configure the Settings tab, click Next to proceed to the Existing API tab, or click Prev to return to the Profile tab.

Existing API tab

Use the Existing API tab to specify the base URL of the API you want to proxy and optionally provide an OpenAPI document for automatic service discovery.

Configure the following settings:

• Base API URL: Enter the base URL of the API to proxy.

  Note

  If the API provides a single service, you can enter the complete API URL, including the service path. Additional service paths are defined in the Services tab.

• Provide OpenAPI document: If you provide an OpenAPI document, API Manager uses it to auto-discover the API's services. Select No to skip or Yes to expand an additional area for providing the OpenAPI document:

  

  • Load URL: Opens a dialog to load an OpenAPI document in YAML or JSON format from a URL:

    

  • Upload file: Opens a dialog to upload an OpenAPI document in YAML or JSON format after you use Browse to select the file:

    

  • Clear: Clears an OpenAPI document that has already been provided and changes the Provide OpenAPI document selection to No. A Clear editor contents confirmation dialog appears, asking you to confirm before the document is removed. Clearing the document also removes any services that were automatically discovered from it (see OpenAPI document auto-discovery), but does not affect manually added services or other API settings. Clearing the document is treated as an unsaved change until you save the API configuration.

  • Document editor: Allows viewing and editing of a provided OpenAPI document. You can also provide an OpenAPI document by entering it here directly. To view and edit the OpenAPI document in a larger area, click the popout icon. After opening that area, click the return icon to come back to this screen.

After you configure the Existing API tab, click Next to proceed to the Services tab, or click Prev to return to the Settings tab.

Services tab

Use the Services tab to define the services and HTTP methods that the proxy API will expose. The way in which you define services depends on whether you provided an OpenAPI document in the Existing API tab.

Manual service definition

If you did not provide an OpenAPI document, you must define services and methods manually:

Click New Service to add a service. Configure the following settings:

• Service Name: Enter a name to identify the service.

• Path: Enter a path for the service. If the API does not have a service path, enter a forward slash (/). To define a path parameter, wrap its name in curly brackets (for example, /pets/{petId}). For the characters and limits that a path accepts, see Service path rules.

• Methods: Select each method to be created for the service. Available methods include GET, PUT, POST, and DELETE. To use a method not listed, enter the method name in the Type a new method text box and press Enter.

• Actions: Hover over a service row to reveal additional actions.

  • Copy API service URL: Click to copy the API's service URL.
  • Duplicate: Click to duplicate the service.
  • Delete: Click to delete the service.

You must add at least one service to proceed to the next tab.

OpenAPI document auto-discovery

If you provided an OpenAPI document in the Existing API tab, API Manager automatically discovers and lists services in a table:

• Assign: Use the toggle to add the services to the proxy API.
• Service Name: The name used to identify the service. When the document defines more than one method for the same path, the name includes the method (for example, GET /pets and POST /pets) so that each name is unique. A path with a single method uses the path as the name.
• Methods: The HTTP method that applies to the service. This field is read-only because the methods come from the OpenAPI document.
• Path: The path of the service.

• Actions: Hover over a service row to reveal additional actions.

  • Copy API service URL: Click to copy the API's service URL.

API Manager also detects the path, query, and header parameters that the document defines for each path and method, and lists them on the service parameter tabs.

Service parameters

Select a service row to expand it and view the parameters for that service. Parameters are stored for each combination of path and HTTP method. If a service has more than one method, a tab for each method (for example, GET and POST) appears above the parameter tabs, and each method tab has its own parameters.

The Required setting on query parameters and headers marks a parameter as required in API Manager and the API Portal. The API Portal prevents you from testing a request that omits a required parameter. The API gateway does not check for required parameters when it forwards requests to the existing API, so the existing API must validate them.

Path params tab

This tab lists the path parameters for the service:

• Parameter: The name of each path parameter. API Manager adds a parameter automatically for each name that you wrap in curly brackets in the Path, following the Service path rules. This field is read-only. A consumer must provide a value for every path parameter when calling the service.

• Description: A read-only field. API Manager does not store descriptions for path parameters.

Query params tab

This tab lists the query parameters for the service. Query parameters are detected from an OpenAPI document or added manually:

• Add Parameter: Click to add a query parameter to the service. The following fields become available:

  • Parameter: Enter the name of the query parameter. For the allowed characters and length, see Parameter name rules.

  • Description: Optionally, enter a description of the query parameter.

  • Required: Use the toggle to mark the query parameter as required. The default is disabled.

  • Delete: Click the delete icon next to a query parameter to delete that parameter.

Headers tab

This tab lists the request headers that consumers can send to the service. These headers describe what the existing API accepts. To set header values that API Manager sends to the existing API, use the Request headers tab instead.

• Add parameter: Click to add a request header to the service. The following fields become available:

  • Parameter: Enter the name of the request header. For the allowed characters and length, see Parameter name rules.

  • Description: Optionally, enter a description of the request header.

  • Required: Use the toggle to indicate that consumers must send the header. The default is disabled.

  • Delete: Click the delete icon next to a request header to delete that header.

Parameter name rules

API Manager validates parameter names and descriptions when you edit them. You must resolve all errors before you can publish the API:

• Parameter names cannot be empty or duplicated within the same tab.
• Parameter names cannot exceed 64 characters, and descriptions cannot exceed 256 characters.
• Query parameter names can contain only letters, numbers, and the characters -, ., and _.
• Header parameter names can contain only English letters, numbers, and the characters !, #, $, %, &, ', *, +, -, ., ^, _, `, |, and ~.

Service path rules

API Manager validates the Path of each service, whether you enter it manually or it comes from an OpenAPI document. An error appears under the Path field, and you must resolve it before you can publish the API. A path must follow these rules:

• The path starts with a forward slash (/). API Manager adds the slash automatically.
• The path cannot exceed 2000 characters.
• Each text segment of the path (the parts outside curly brackets) can contain only letters, numbers, and the characters -, _, and .. Letters and numbers can be from any language.
• A path cannot contain empty segments (//).
• Curly brackets must be paired and cannot be nested or empty. A path parameter name inside the brackets follows the same character rules as text segments and cannot exceed 64 characters. A path cannot use the same parameter name twice.
• A path can end with a forward slash, and text and parameters can share a segment (for example, /report.{format}).
• A service can use the base path (/) with no additional segment, and the base path can have multiple methods.

After you configure the Services tab, click Next to proceed to the Security profiles tab, or click Prev to return to the Existing API tab.

Security profiles tab

The Security profiles tab is optional and allows you to restrict access for consumption of the API.

Configure the following settings:

• Assign: Use the toggle to assign or unassign security profiles for the API.

• Profile Name: The name of the security profile as configured in Security Profiles.

• Type: The authentication type for the security profile, such as Basic, OAuth 2.0, or API Key.

• User Name: For basic authentication, this displays the username. For other authentication types, this displays the same value as the Type column.

• Actions: Hover over a security profile row to reveal additional actions.

  • Go to security profile: Click to open the security profile's configuration.

Depending on the Harmony organization's policies, you may be required to assign a security profile in order to save the API.

Click New security profile to create a new security profile. For instructions, see Configure security profiles.

After you configure the Security profiles tab, click Next to proceed to the Request headers tab, or click Prev to return to the Services tab.

Request headers tab

The Request headers tab is optional and allows you to add new request headers or override existing request headers.

Click New header to add a request header. Configure the following settings:

• Key: Enter a key for the request header. The key can contain only letters, numbers, hyphens (-), and underscores (_). Spaces, multibyte characters, and other special characters are not allowed.

• Value: Enter a value for the request header. The value can contain only printable ASCII characters (letters, numbers, and standard punctuation), with no leading or trailing spaces, and cannot exceed 8192 characters. Multibyte and control characters are not allowed. This accommodates values such as JSON Web Tokens (JWTs), which require periods (.) as part of their format.

• Override Incoming: Enable this toggle to override an existing request header that uses the same Key. The default is disabled.

• Actions: Hover over a header row to reveal additional actions.

  • Delete: Click to delete the request header.

After you configure the Request headers tab, click Publish to publish the API, or click Save as draft to save your progress.

Save and publish options

After you configure all required tabs, you can save or publish the API:

• Save as draft: Saves the API in Draft status or Published with Draft status. Draft APIs do not count against your Proxy URL subscription limit. An API whose status was Published at the time you use Save as draft is saved as Published with Draft. A published API counts against your Proxy URL subscription limit, even though its draft is not accessible.

• Publish: Saves the API in Published status. The API is live and accessible within five minutes. A published API counts against your Proxy URL subscription limit. A dialog indicates the API is live:

  

  The dialog provides these options:

  • Copy URL: Copies the API's service URL to your clipboard.
  • Close: Closes the dialog.

Edit the API

After you save the API, you can edit it from these locations:

• Using card view in the APIs page, click the card.
• Using list view in the APIs page, click Edit in the Actions column.

When editing a published API from list view, a Documentation tab is also available. Use this tab to view, edit, and publish OpenAPI documentation for individual APIs. For details, see Documentation tab on the APIs page.

Troubleshooting

For related troubleshooting, see the following in the API Manager troubleshooting guide:

• Cloud proxy API: Target API must be publicly accessible

• Proxy API: Request header hyphens replaced with underscores

• Show Request & Response Payloads setting has no effect for proxy APIs