> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# IBM API Connect

> Connect IBM API Connect so agents can review catalogs, published APIs, analytics, governance rulesets, and AI gateway usage

Connect IBM API Connect and CloudThinker agents can review catalogs and published APIs, API errors and latency, governance rulesets, and AI gateway usage. The connection signs in with an API Connect **API key** and the platform **client ID** and **client secret** of your provider organization.

> [!NOTE]
>
> IBM API Connect isn't turned on for every workspace yet. To use it, [contact us](https://cloudthinker.io/contact).

## Prerequisites

* API Connect v10.0.10 or later, or API Connect v12, on IBM's cloud service or on your own servers.
* For v10, **API Agent** enabled on your instance, and a user with the **api-agent** role in the provider organization. See IBM's [API Agent documentation](https://www.ibm.com/docs/en/api-connect/software/10.0.x_cd?topic=creating-deploying-publishing-apis-using-api-agent).
* An HTTPS path from CloudThinker to the platform and management API addresses. This connection runs from CloudThinker Cloud. If your instance only accepts known addresses, allow CloudThinker's egress IPs: these docs don't publish the list, so ask your CloudThinker contact, or [contact us](https://cloudthinker.io/contact). See [Reaching private services](https://docs.cloudthinker.io/guide/connections/overview.md#reaching-private-services).
* The **Admin** role in your CloudThinker workspace, which can add and edit connections. See [Roles](https://docs.cloudthinker.io/guide/security/roles.md).

## Choose a connection

On v10, one connection covers everything. On v12, IBM splits API Connect into services, and each one is its own connection with the same fields. Add only the ones you need.

| Connection | Version | What it covers |
| - | - | - |
| **IBM API Connect v10** | v10.0.10 or later | Catalogs, published APIs and products, analytics, governance, and gateway policies |
| **IBM API Connect v12 Management** | v12 | Catalogs, spaces, products, plans, consumer organizations, apps, and subscriptions |
| **IBM API Connect v12 Analytics** | v12 | API status, usage, latency, and consumers |
| **IBM API Connect v12 Governance** | v12 | Governance rulesets and API definition validation |
| **IBM API Connect v12 GenAI** | v12 | Gateway policies, and drafts of API specifications, policies, and rules |
| **IBM API Connect v12 AI Gateway** | v12 | AI providers, LLM token usage, and MCP traffic |

## Setup

**1. Create an API key**

Sign in to API Manager as the user CloudThinker should act as. Open the profile icon at the top right and select **My API Keys**. Click **Add**, enter a **Title** and **Description**, and choose a timeout long enough to cover your use. Select **Enable multiple use** and click **Create**. Copy the key.

**2. Find the client ID, client secret, and URLs**

On the **My API Keys** page, scroll to **Authenticating for the platform REST API**. In its example `curl` command:

* The **client ID** and **client secret** are the `client_id` and `client_secret` values.
* The **Platform URL** is the address before `/api/token`.

On v10 installed on your own servers, the client ID and secret are also in the `toolkit` section of the Toolkit credentials file you download from API Manager. Use these platform credentials, not a consumer app's credentials. For the **Management URL**, ask your API Connect administrator for the HTTPS address of the management API.

**3. Add the connection in CloudThinker**

In the sidebar, click **More → Workspace settings → Connections**. On the **Builtin Connections** tab, search for **IBM API Connect**, pick the connection from [Choose a connection](#choose-a-connection), and click **Connect**. Fill in the fields from [Connection details](#connection-details) and click **Connect**.

**Success state:** the connection shows **Connected**. Repeat this step for each v12 service you want.

## Connection details

| Field | Description | Example |
| - | - | - |
| **Provider organization** | The provider organization name in API Connect | `my-org` |
| **API key** | The key from step 1 | `<your-api-key>` |
| **Client ID** | The platform client ID from step 2 | `<your-client-id>` |
| **Client secret** | The platform client secret paired with that client ID | `<your-client-secret>` |
| **Platform URL** | The platform API address, with `https://` and no path | `https://platform-api.example.com` |
| **Management URL** | The management API address, with `https://` and no path | `https://api-manager.example.com` |

Both URLs must use HTTPS with a trusted certificate. CloudThinker connects only to these two addresses and refuses redirects to anywhere else.

## Required permissions

Agents can do what the API key's user can do in the provider organization.

| Goal | What the user needs |
| - | - |
| Use the v10 connection | The **api-agent** role, with **API Agent** enabled on the instance |
| Read catalogs, APIs, products, and analytics | Access to those catalogs in the provider organization |
| Read governance rulesets | Access to governance in the provider organization |

> [!TIP]
>
> Create a dedicated API Connect user for CloudThinker, give it only the catalogs agents should see, and set the API key timeout to match how long you want the connection to work.

## Agent capabilities

| Capability | What agents can do |
| - | - |
| **Catalogs and publishing** | List catalogs, spaces, published APIs, products, plans, and gateways |
| **Consumers** | List consumer organizations, apps, and subscriptions |
| **API analytics** | Show API status, usage, errors, latency, and top consumers over the last day |
| **Governance** | List rulesets and their rules, validate API definitions and products against them, and suggest fixes |
| **Gateway policies** | List gateway policies, and draft or modify a policy |
| **Drafts** | Draft an OpenAPI specification, improve an existing one, or draft a Spectral governance rule |
| **AI gateway** | List AI providers, and show LLM token usage and MCP request usage over the last day |

Reads run without asking. Validation and draft tools go through your [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. Drafts stay with the agent: nothing is published to API Connect.

Agents can't create apps or subscriptions, publish products, change rulesets, or read consumer app credentials. Make those changes in API Manager.

### Verify the connection

```text theme={null}
List my API Connect catalogs and the APIs published in the sandbox catalog
```

A working connection returns your catalog names and the published APIs in that catalog.

### Example prompts

```text theme={null}
Which APIs in the production catalog had the most errors in the last day?
Validate this OpenAPI definition against our governance rulesets and suggest fixes
```

## Troubleshooting

> [accordion] API Connect requires a valid PROVIDER\_ORG value.
>
> A field is empty or contains a line break. The field named in the message is one of **Provider organization**, **API key**, **Client ID**, **Client secret**, **Platform URL**, or **Management URL**. Fill it in and connect again.

> [accordion] API Connect APIC\_PLATFORM\_URL must use HTTPS with no path, credentials, query, or fragment.
>
> The **Platform URL** (or **Management URL**, for `APIC_MANAGEMENT_URL`) isn't a bare HTTPS address. Enter only `https://` and the host, such as `https://platform-api.example.com`.

> [accordion] API Connect request refused by endpoint or response policy.
>
> API Connect redirected the request to another address, didn't answer within 30 seconds, or sent an unusually large response. Check that both URLs are the exact platform and management API addresses, not addresses that redirect.

> [accordion] Connected, but the v10 tools fail
>
> Check that **API Agent** is enabled on the instance and that the API key's user has the **api-agent** role in the provider organization.

> [accordion] Connected, but requests fail after a while
>
> The API key's timeout ran out, or the key wasn't created with **Enable multiple use**. Create a new key and update the connection.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Use platform credentials only.** Enter the platform client ID and secret, never a consumer app's credentials.
- **Limit the user.** Give the API key's user access to only the catalogs agents should see.
- **Set a key timeout.** An API key with a timeout stops working on its own if you forget to revoke it.

## Related

> [card] [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md)
>
> Decide which changes run, wait for a person, or are refused

> [card] [Connections](https://docs.cloudthinker.io/guide/connections/overview.md)
>
> Every service CloudThinker can connect to


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.