IBM API Connect is a comprehensive API management platform that enables administrators to govern the full API lifecycle. Its proxy capability acts as an intelligent intermediary between API consumers and backend services by intercepting incoming requests and outgoing responses, enabling a wide range of transformations and policies. This interception also facilitates monitoring and analytics, providing administrators with critical insights into API usage and performance.

This article describes how to integrate IBM API Connect with the Cequence Unified API Protection (UAP) platform to discover and protect the APIs that IBM API Connect manages. You can implement Custom Gateway Scripts and Global Policies to extend gateway functions to change the API flow to meet specific requirements and use cases.

To integrate with the Cequence UAP platform, IBM API Connect must send all request and response data to the Cequence UAP platform's traffic ingestion API using Custom Global Policies.

The custom Global Policies in IBM API Connect use Gateway Scripts that synchronously process request and response data. The data is sent to the Cequence Bridge in the required JSON format before being forwarded to the Cequence API Edge server, which processes the transactions and provides insights into the API traffic.

High-level architecture

The following diagram shows the API call flow between IBM API Connect and the Cequence UAP platform.

API call flow diagram showing the integration between IBM API Connect and the Cequence UAP platform

Note: The term "Assembly" refers to a set of policies and configurations applied to an API endpoint within the API Gateway. Assemblies are collections of instructions that determine how to handle an API request and response.

The IBM API Connect API Gateway receives incoming API requests. The pre-hook global policy intercepts each request, capturing the request payload and metadata.
The request flows through the Assembly for further processing and moves on to the backend or target application.
A response is received from the origin server. Any applicable policies in the Assembly execute, and the post-hook global policy captures the response payload and metadata.
The request and response payload and metadata are synchronously posted to the Cequence Bridge, which forwards the transaction to the Cequence UAP Edge for threat analysis, detection, and mitigation.
Cequence Bridge synchronously responds with a success acknowledgment. If the call to Cequence Bridge fails, the failure occurs silently without disrupting the actual traffic.
The origin server's response is returned to the client.

Terms used in this article

The following terms have specific meanings in the context of IBM API Connect.

Catalog: A staging target that behaves as a logical partition of the gateway and the Developer Portal. The URL for API calls and the Developer Portal are specific to a particular Catalog. In a typical configuration, an API provider organization uses a development Catalog to test APIs under development and a production Catalog to host APIs that are ready for full use. A common approach is to have a development cloud with a development Catalog, a few test Catalogs, and a production cloud with a dedicated test Catalog.

Space: A partition within a Catalog that enables multiple product teams to manage Products and APIs independently in a single Catalog. A Space behaves like a sub-catalog, except that Products and APIs in all Spaces in a given Catalog are published to the same Developer Portal.

Prerequisites

Confirm that the following prerequisites are in place before beginning the installation procedures.

IBM APIC SaaS tenant.
IBM APIC CLI V10.
The jq filtering utility. Download jq from the repository.
Cequence UAP platform release 7.3 or later.
A Client ID and Client Secret generated from the Cequence UAP platform UI.
Cequence Bridge deployed close to the customer's IBM API Connect tenant.
Cequence Bridge transactions endpoint.

Detailed prerequisites setup

The following procedures establish several of the prerequisites listed above.

Establishing a client ID and client secret

Several Cequence components must authenticate to the Cequence UAP platform in order to transmit and receive data. Create authentication credentials in the Cequence UAP platform to enable this authentication.

Log in to the UAP management portal UI.
The URL for the management portal is typically of the form https://ui.<your-tenant-name>.<domain>. Replace <your-tenant-name> with the name of your Cequence tenant organization. Replace <domain> with your domain name.
Select General Settings > User Management.
The User Management pane appears.
Click the Clients tab.
Click Add New Client.
The new client dialog box appears.
Type the client name in the Client Name field.
This name is the client ID. Note the client ID for later use.
Enable the Traffic Management toggle.
(Optional) To change the token lifespan from the default of 1800 seconds, type a whole number of seconds in Token Lifespan.
Click Save.
A dialog box with the client secret appears.
Click the blue Copy icon to copy the secret to the clipboard, then click Close.
The client is now set up. Note the client name for future use.
The client list appears.
Note the value of the client secret for later use. This value will not be shown again later on the UI for security reasons.

Installing IBM APIC CLI V10

The IBM APIC CLI is required to deploy Global Policies, which cannot be deployed through the IBM API Connect UI. The following steps download the toolkit and set up the required directory structure.

From the IBM API Connect dashboard, select Tools For Download.
Select the link for the operating system of the host where the APIC toolkit will run.

From a terminal, run the following commands to set environment variables and create the required directory structure.

mkdir -p $HOME/cequence && cd "$_"
export CEQUENCE_HOME=$(pwd)
cp <DOWNLOAD_DIR>/cequence-apic-<version>.tar.gz $CEQUENCE_HOME
tar -xvzf cequence-apic-<version>.tar.gz
cd cequence-apic
export CEQUENCE_APIC_HOME=$(pwd)
mkdir $CEQUENCE_APIC_HOME/cli

Copy the toolkit archive downloaded from the IBM dashboard to the $CEQUENCE_APIC_HOME/cli folder.
- On Linux, copy toolkit-linux.tgz.
- On macOS, copy toolkit-mac.zip.
Extract the archive.
- On Linux, run the following command.
```
tar -xvzf toolkit-linux.tgz
```
- On macOS, run the following command.
```
unzip toolkit-mac.zip
```

The apic CLI tool is now in the cli folder.

Plugin installation

Installing the plugin takes place over several tasks that you perform in sequence.

Downloading and extracting the plugin archive file

Download the compressed plugin archive file.
Extract the compressed archive file to the $CEQUENCE_APIC_HOME directory.

Setting up the IBM APIC Cequence .env file

The .env file contains the configuration that connects the plugin to your IBM API Connect environment and the Cequence UAP platform. Confirm that all prerequisites are in place before beginning this procedure.

From the $CEQUENCE_APIC_HOME/scripts directory, run the following command to copy the .env_example file to a new .env file.
```
cp .env_example .env
```
Set environment variables as required by your IBM API Connect environment.
- To create a new API key, from the top-right corner of the dashboard, select the user icon, then select My API Keys, then select Add.
- Copy the API key and note it for later use. In the .env file, set the value of CEQUENCE_IBM_SERVER to the URL that appears after the --server string in the Use API key with APIC CLI field.
- Navigate to APIC Settings and set a value for CEQUENCE_IBM_ORGANIZATION. The organization name is a short identifying label for your organization.

Key attributes in the .env file

The following attributes control plugin behavior and can be adjusted after initial setup.

# Whether to deploy to all catalogs and spaces
CEQUENCE_IBM_DEPLOY_TO_ALL_CATALOGS_AND_SPACES="false"
# Whether to delete the Cequence global policies (for rollback)
CEQUENCE_IBM_DELETE_GLOBAL_POLICIES="false"
# Whether to skip deploying the global policies to the sandbox catalog
CEQUENCE_SKIP_SANDBOX_CATALOG="false"
# Whether to enable x-cequence response headers for debugging
CEQUENCE_ENABLE_CUSTOM_RESPONSE_HEADERS="false"
# Cequence Bridge URL provided by the Cequence team
CEQUENCE_BRIDGE_URL="https://bridge.org.cequence.ai/api-transactions"
# Bridge call timeout in seconds (connect + idle). Range: 1–60. Default: 1.
# Calls that exceed this limit are marked FAILED and that transaction's data
# is not delivered.
CEQUENCE_BRIDGE_TIMEOUT="1"
# Maximum request body size in bytes captured and sent to Cequence Bridge.
# Transactions with larger bodies are SKIPPED. Default: 32000.
CEQUENCE_MAX_REQ_BODY_SIZE="32000"
# Maximum response body size in bytes captured and sent to Cequence Bridge.
# Transactions with larger bodies are SKIPPED. Default: 32000.
CEQUENCE_MAX_RES_BODY_SIZE="32000"
# Response Content-Types captured by the post-hook. Other types are SKIPPED.
# A missing or empty Content-Type is still captured.
# Default: application/json, application/xml, text/xml, application/soap,
# application/soap+xml, application/x-www-form-urlencoded (text/html excluded).
# To customize, supply a JSONata regex literal. Use single quotes so bash does
# not expand '$' or '\' when sourcing .env.
CEQUENCE_RES_CONTENT_TYPES=''
# POOL ID / region identifier for source_info.pool_id (optional).
# When empty, the value is derived from the second label of the request host.
POOL_ID=""
# Global flat sample rate (0.0–1.0), applied to both reads and writes.
# A value of 0.1 captures approximately 10% of non-priority traffic, letting
# the remainder bypass Cequence Bridge entirely to keep latency low.
# Set to 1.0 to disable sampling.
CEQUENCE_SAMPLE_RATE="0.1"

To deploy to selected catalogs and spaces, create a config.jsonc file by copying the template.

cp config-template.jsonc config.jsonc

The following excerpt shows sample contents of a config.jsonc file.

{
  // Catalog where all spaces are included for deployment
  "sandbox": [], // NOTE: The value is an empty array
  "catalog_1": [],
  "catalog_2": [],
  // Catalog where only specific spaces are included for deployment
  "catalog_3": ["space_1"], // NOTE: The value is an array of spaces
  "catalog_4": ["space_1", "space_2"]
}

Logging on to the IBM API Connect CLI

Run the following commands from a terminal to log on to the IBM API Connect CLI.

From the $CEQUENCE_APIC_HOME/cli directory, run the following command.
```
source $CEQUENCE_APIC_HOME/scripts/.env
```

Run the login command for your operating system.

On Linux, run the following command.

./apic login --sso --context provider --server $CEQUENCE_IBM_SERVER --apiKey $CEQUENCE_IBM_API_KEY

On macOS, run the following commands.

chmod +x apic
xattr -d com.apple.quarantine apic
sudo ./apic login --sso --context provider --server $CEQUENCE_IBM_SERVER --apiKey $CEQUENCE_IBM_API_KEY

Cloud administration commands

Run the following commands to retrieve information about your IBM API Connect environment before deploying policies.

From the $CEQUENCE_APIC_HOME/cli directory, run the following command to retrieve the names of the configured gateway services.

./apic configured-gateway-services:list --org $CEQUENCE_IBM_ORGANIZATION --server $CEQUENCE_IBM_SERVER --scope catalog --catalog sandbox

Set the value of CEQUENCE_IBM_CONFIGURED_GATEWAY_SERVICES to the first result from the previous command.
```
export CEQUENCE_IBM_CONFIGURED_GATEWAY_SERVICES=apic-gwv6a-xa3
```

Run the following command to list existing global policies.

./apic global-policies:list-all --scope catalog --catalog sandbox --server $CEQUENCE_IBM_SERVER --org $CEQUENCE_IBM_ORGANIZATION --configured-gateway-service $CEQUENCE_IBM_CONFIGURED_GATEWAY_SERVICES

Deployment configuration

You can apply policies using one of two approaches.

Approach 1: Global deployment to all catalogs and spaces

To deploy Cequence Global Policies to all catalogs and spaces, set the value of CEQUENCE_IBM_DEPLOY_TO_ALL_CATALOGS_AND_SPACES in the .env file to true.

Approach 2: Deployment to specific catalogs and spaces

In the .env file, set CEQUENCE_IBM_DEPLOY_TO_ALL_CATALOGS_AND_SPACES to false.
From the $CEQUENCE_APIC_HOME/scripts directory, create a config.jsonc file from the template.
```
cp config-template.jsonc config.jsonc
```
From the $CEQUENCE_APIC_HOME/cli directory, run the following command to retrieve the list of catalogs.
```
./apic catalogs:list --org $CEQUENCE_IBM_ORGANIZATION --server $CEQUENCE_IBM_SERVER
```

To retrieve the list of spaces within a catalog, run the following command.

./apic spaces:list --org $CEQUENCE_IBM_ORGANIZATION --server $CEQUENCE_IBM_SERVER --catalog <catalog-name>

Excluding APIs from the Cequence global policy

To exclude specific APIs from the Cequence Global Policy, add a property called isExcludedFromCequenceGlobalPolicy with a value of true at the API level or Catalog level. This property can only be modified from the IBM APIC UI.

From the Gateway tab, select the + icon next to Properties.
Enter isExcludedFromCequenceGlobalPolicy as the name.
Enter true as the value.
Select Add.
Select Save.

Installing Cequence global policies

Global Policies can only be deployed through the CLI. Run the following commands from the $CEQUENCE_APIC_HOME/scripts directory.

chmod +x *.sh
./deploy.sh

Monitor the output for any errors. When the script finishes running, confirm that a success message appears.

Testing the plugin setup

Testing the integration

To confirm that the integration is working, send a curl or Postman request to any API deployed in a catalog or space where the plugin or policy is enabled.

When CEQUENCE_ENABLE_CUSTOM_RESPONSE_HEADERS is set to true, the response headers include x-cequence-headers.

Verifying transactions in the Cequence UAP platform

From the Cequence UAP platform, navigate to the transactions view and confirm that transactions appear.

Rollback

Use the rollback script to delete all Cequence resources created during installation. You can also delete the API, Product, Consumer Org, Catalog, and User Registry manually from the dashboard.

Note: Global policies can only be removed through the CLI.

To roll back the installation using the script, in the .env file set the value of CEQUENCE_IBM_DELETE_GLOBAL_POLICIES to true, then run the following command from the $CEQUENCE_APIC_HOME/scripts directory.

./rollback.sh