Migrate from IBM API Connect to WSO2 API Manager

A plan for moving APIs, products, plans and consumer applications from IBM API Connect to self-hosted WSO2 API Manager, covering what transfers cleanly, what needs rework and how to cut over safely.

On this page

Migrate from IBM API Connect to WSO2 API Manager: what the work involves

Moving from IBM API Connect to WSO2 API Manager is a re-platforming of the publisher, gateway, catalog and consumer onboarding, not a file copy. The exported OpenAPI definitions carry the contract, but the policies, plans, subscriptions and credentials that make those APIs work for consumers have to be rebuilt in WSO2's model and then re-issued. Most organizations that pay for a renewal, face a pricing change, or need APIs to stay in their own data center start by inventorying what the estate actually does, not by exporting it. A platform team usually leads the work and brings in an implementation partner for the mapping, the gateway build and the cutover plan, while the API owners keep the decisions about who may call what.

Effort and risk are driven less by the number of APIs than by how much logic sits in API Connect assembly policies and gateway scripts. Each assembly step, such as rate limiting, JWT validation, transformation or header handling, has to be mapped to a WSO2 mediation sequence, a throttling policy or a custom authenticator, and any behavior with no direct equivalent needs a design decision. Confirm with WSO2 which of your specific policies are covered by built-in mediation and which need custom code, and confirm which extension points your team will maintain. The WSO2 repository lists custom authenticators, policies and workflows as supported extensions, but the exact mapping for your policy set has to be tested, not assumed.

Consumer re-onboarding is the part most likely to slow a cutover. Products, plans, consumer organizations and applications in API Connect do not transfer as a single bundle into the WSO2 publisher and developer portal, so each subscribing application needs to be recreated, linked to the right plan and issued new credentials. Plan a parallel period in which old and new gateway endpoints both serve traffic, agree with each consumer team on a dated switch, and keep an inventory of which clients still call the old endpoints. Ask any implementation partner to show how they will move keys and secrets securely, how they will test each policy against recorded traffic, and how rollback works if a consumer fails after the switch.

Which API Connect capabilities map to WSO2 API Manager, and where the gaps sit

This table maps the main API Connect capabilities to their closest WSO2 API Manager equivalents and marks each row as clean, needs rework or gap. Use it to scope the migration work, then confirm analytics and policy parity against your own API Connect exports and a proof-of-concept gateway before you commit to a plan.

CapabilityAPI ConnectWSO2 API Manager and what to check
API definitions (OpenAPI)Clean: OpenAPI documents exported from the API Manager or Toolkit can be reused as the basis for WSO2 APIsClean: WSO2 supports REST, GraphQL and AsyncAPI, so confirm each API type is covered by your design and test the imported definitions
Products and plansNeeds rework: products bundle APIs and plans that define rate limits and accessNeeds rework: WSO2 uses its own subscription tiers and throttling policies, so rebuild each plan and map limits by hand
Consumer organizations and catalogsNeeds rework: consumer orgs and catalogs group consumers and visibilityNeeds rework: map these to WSO2 developer portal visibility and subscription groups, then confirm access rules with your own owners
Applications and credentialsGap in direct transfer: client IDs and secrets are issued per applicationNeeds rework: credentials must be re-issued in WSO2, so plan consumer communication and key rotation windows
Assembly policiesNeeds rework: assembly policies run as ordered steps in the gatewayNeeds rework: map each policy to a WSO2 mediation sequence or custom policy, and test behavior with real payloads
Gateway scripts (JavaScript)Gap: gateway scripts run in the API Connect runtimeGap: scripts must be rewritten as WSO2 mediation logic or custom Java extensions, so budget engineering review
Developer portalNeeds rework: the API Connect portal hosts docs and sign-upNeeds rework: WSO2 Developer Portal covers docs and subscriptions, but branding and content must be rebuilt and checked
Analytics and reportingGap in parity: dashboards and reporting depend on API Connect analyticsGap in parity: confirm which metrics WSO2 exposes and whether existing dashboards and alerts can be reproduced in your environment
Deployment optionsNeeds rework: SaaS on AWS or IBM Cloud, or self-managed with DataPower gatewaysNeeds rework: WSO2 supports on-premises packages, managed cloud, and Kubernetes via WSO2 API Platform for Kubernetes, so choose a target and validate sizing

What to export from API Connect and what to rebuild in WSO2

Moving from API Connect to WSO2 API Manager is less a file copy than an inventory exercise. Some artifacts carry over as definitions, some must be rebuilt as WSO2 objects, and some (credentials and consumer relationships) need a deliberate cutover plan. The cards below separate those three groups so each one gets an owner and a check before the first production consumer moves.

OpenAPI definitions as the primary artifact

The OpenAPI documents behind each API Connect product are the most portable thing you own. Export the current, published version of every API definition from API Connect, not the draft in a developer workspace, and record which operations are actually routed by the gateway. Check that the export format and any extensions your team added (for example, vendor-specific x- fields that API Connect reads) are handled by WSO2 API Manager as you expect. Confirm the export method and format with IBM and WSO2 documentation before scripting it.

Products, plans and rate limits

API Connect products bundle APIs with plans that set rate limits, quotas and access rules. Those bundles do not move automatically. Map each product to a WSO2 API Manager API (or API product) and each plan to a throttling policy, then document the limit values, time windows and which consumers hold which tier. Use an illustrative spreadsheet with one row per product and plan so reviewers can sign off the mapping before anything is created in WSO2.

Consumer organizations and applications

API Connect tracks consumer organizations, their members and the applications they register against each plan. Export these records as a list keyed by organization, application name and subscribed product. In WSO2 API Manager, subscriptions and applications are created by the consumer through the Developer Portal, so plan a move in which consumers re-subscribe to the new catalog. Confirm with WSO2 documentation which of these objects can be bulk-created through the REST APIs and which need manual steps.

Client credentials that must be re-issued

Client IDs and secrets issued by API Connect are not carried into WSO2 API Manager as working credentials, so every consuming application needs new keys. Build a cutover list from the application records, identify which consumers store secrets in vault systems and which hard-code them, and agree a dual-running window in which both old and new credentials are accepted at the edge. Your security team should confirm how old secrets are revoked and logged, and that no secret is written into exported files or tickets.

Backend authentication and gateway scripts

API Connect assembly policies and GatewayScript run in the DataPower gateway and call backends with credentials that were configured there. Inventory every backend connection, its authentication method (basic, OAuth client credentials, mutual TLS or API keys) and every custom script. Scripts are not exported as WSO2 configuration. Each one must be rewritten as WSO2 mediation sequences or as a custom policy, and each backend credential must be re-entered through a secure store, not copied from the old gateway configuration.

Webhooks and event consumers

Some APIs feed webhooks or event consumers that sit outside the API layer and call back into your systems or subscribe to published events. These integrations depend on the gateway's URL, certificate and response behaviour, so changing the gateway changes them. List each webhook sender and receiver, the hostname or path it uses and its retry expectations. Plan a change window where the receiving side updates its endpoint, and test delivery and signature checks in a staging environment first.

Migration sequence from inventory to decommission

This sequence moves API Connect workloads to WSO2 API Manager in controlled stages, so each API, consumer organization and credential is verified before the next group moves. It ends with a documented decommission of the legacy estate.

  1. Build the API inventory and classify each API

    The platform team exports the catalog of products, APIs, plans, consumer organizations and applications from API Connect, then records the OpenAPI definition version, the assembly policies and gateway scripts behind each API, the backing services and the traffic volume and consumer criticality. Each API is tagged by risk and by dependency so that low-risk candidates can be identified. The output is an API inventory that the owning teams have reviewed, with every API assigned a migration wave. Ask your IBM contacts or your own export tooling to confirm what the export includes, since some plan and application metadata may need to be captured manually.

  2. Create the mapping register for policies and scripts

    For each API in the inventory, the architects record how every assembly policy, rate limit, JWT or OAuth check, transformation and gateway script maps to a WSO2 API Manager mediation sequence, custom policy or built-in throttling configuration. Items with no direct equivalent are flagged with a design decision, a proposed replacement and an owner. Security reviewers check authentication and throttling mappings against the original behavior. The output is a mapping register that links each source artifact to its target configuration and records any gap that needs a decision before pilot work starts.

  3. Stand up WSO2 API Manager 4.7.0 and run a pilot

    The team deploys WSO2 API Manager 4.7.0 in a non-production environment, either from the released distribution or built from source, which requires JDK 21. They import the OpenAPI definition for one low-risk, read-heavy API, rebuild its products, plans and subscriptions, and reissue test credentials to a small set of consumers. Functional tests, security tests and load tests compare responses and throttling behavior with the API Connect baseline. The output is a pilot sign-off document signed by the API owner, the security reviewer and the platform lead, listing the accepted differences and any open defects.

  4. Run a parallel period with traffic split by path or consumer

    Both platforms stay live while a routing layer, such as a DNS or reverse proxy change, sends selected paths or named consumer organizations to WSO2 API Manager. The team compares request logs, error rates, latency and throttling outcomes between the two gateways and resolves discrepancies in the mapping register. Consumer teams confirm that their applications work with the new endpoints and credentials. The output is a parallel run report showing agreed parity for each wave, plus a list of consumers ready for cutover.

  5. Plan the staged cutover of consumer organizations

    Consumer organizations move in groups rather than all at once. For each group, the team writes a cutover runbook covering the freeze window, the order of DNS or gateway changes, credential reissue and distribution, rollback steps and the named person who authorizes rollback. Communications go to each consumer organization before its date, and support contacts are staffed during the window. Each group is closed only after its consumers confirm successful calls and API Connect traffic for that group falls to zero. The output is a cutover runbook per wave and a closure record for each completed wave.

  6. Decommission API Connect after the retention period

    Once every wave is closed, the team keeps API Connect in a read-only state for a retention period that the organization sets with its compliance and audit owners. During that period, configuration and log exports are archived under the organization's own retention policy, and the license, subscription or infrastructure commitments are reviewed with procurement. After the period ends, the environments and any DataPower or Kubernetes resources are removed in a controlled change. The output is a decommission record listing the archived artifacts, the final traffic evidence, the approvals and the date each component was shut down.

How to run both platforms in parallel and cut over without breaking consumers

Run API Connect and WSO2 API Manager side by side against the same backend services, and move consumers in stages rather than all at once. The same backends must be reachable from both gateways during the overlap, so confirm that network paths, mTLS trust stores and backend allowlists permit traffic from the WSO2 gateway nodes before any consumer is pointed at them. Start with one consumer organization and a low-risk API product, publish the equivalent API in WSO2 API Manager with the same OpenAPI contract, and route only that organization's traffic to the new gateway hostname. Keep the mediation and throttling settings identical for that cohort so that any difference in behavior is traceable to the platform and not to a changed policy.

Keep API Connect in read-only mode for each migrated product until the rollback window closes. Stop new subscriptions and application registrations in API Connect for migrated products, but leave the existing gateway routes live so that a consumer can be pointed back within minutes. Sequence credential re-issue carefully: publish a deprecation notice with a date, issue new client credentials in WSO2 API Manager to each application, and only revoke old credentials after the consumer confirms a successful call. The deployment model changes these steps. With on-prem installs, you operate the gateways and the control plane, so cutover depends on your own change windows. With hybrid deployment, WSO2 hosts the control plane as SaaS while on-premises gateways serve traffic, so you must confirm how control plane outages affect token issuance and throttling. With fully managed SaaS, cutover steps depend on the DNS and endpoint model WSO2 provides, which you should confirm in writing.

Agree rollback criteria with your change board before the first consumer moves. Typical criteria include error rate and latency thresholds on the migrated cohort, failed authentication from consumer applications, and any throttling mismatch, but the values, measurement windows and owners are decisions for your organization, not something this plan can set for you. Record who can trigger a rollback, how long the old route stays live, and what evidence is needed to close each stage. Ask WSO2 to confirm the support scope for a hybrid or managed deployment during an active cutover, and ask your internal team which consumers have hard-coded hostnames or certificate pinning, since those are the usual reasons a cutover breaks consumers that the catalog did not reveal.

What drives the cost and duration of the move

This table lists the main factors that set the size of a move from API Connect to WSO2 API Manager, with what each one does to cost and how to keep it down. Read the one-time work separately from the recurring costs, and use the last row to shape the written scope and quote.

DriverWhy it changes cost or effortHow to keep it down
Number of APIs and versionsEach API, and each live version that consumers still call, needs its OpenAPI definition exported, checked and published in the Publisher. Old versions often carry the most divergent policies.Inventory APIs by traffic and owner. Retire unused versions before migration and migrate only versions with active consumers.
Assembly policies and gateway scriptsEach DataPower or assembly policy, and each gateway script, must be mapped to WSO2 mediation sequences or an extension. Custom logic takes the most analysis time.Start with a policy-to-mediation mapping sheet. Replace standard policies with built-in features and limit custom code to logic that has no equivalent.
Products, plans and rate limitsProducts and plans in API Connect must be recreated as WSO2 API products, subscription tiers and throttling policies, and each one needs a business decision on limits.Reduce the number of plans. Agree limit values with API owners before the mapping work starts, not during cutover.
Consumer organizations and applicationsEach consumer organization, application and subscription must be re-onboarded, and consumers may need new client credentials and updated endpoints.Pull the subscriber list from existing analytics. Plan a dual-running period and communicate the credential change to each consumer in advance.
Custom authenticators and workflowsCustom authentication or approval workflows built on API Connect must be rebuilt as WSO2 extensions, which requires Java development and testing against the new gateway.Confirm early which custom authenticators and workflows are business-critical. Drop or simplify any that are not used.
Analytics and reporting requirementsDashboards, usage reports and alerting used by operations or finance must be rebuilt on the WSO2 analytics stack or an external tool.List the reports that auditors and owners actually use. Export historical usage data before cutover if retention rules require it.
Deployment target (VMs or Kubernetes)Running WSO2 API Manager on VMs or on Kubernetes through the WSO2 API Platform for Kubernetes changes the infrastructure build, the CI/CD pipeline and the operating skills needed.Choose one target that matches existing platform skills. Use infrastructure as code so that test and production environments match.
WSO2 subscription or open source buildThe Apache-2.0 open source build has no license fee but leaves support, patching and vulnerability monitoring with your team. A subscription adds recurring fees in exchange for vendor support, continuous updates and the licensed distribution for commercial use.Decide this before design starts. Ask WSO2 for written subscription terms, and price your own staff time for patching, upgrades and incident response if you choose the open source build.
One-time versus recurring costOne-time work covers mapping, build, pilot, migration and cutover. Recurring cost covers any WSO2 subscription, hosting, storage, backups and the staff who run the platform.Ask the implementation partner to split the quote into one-time phases and recurring items, with the assumptions behind each line.

What usually goes wrong in an API Connect to WSO2 move

Most failed API Connect migrations break at the edges: gateway logic that was never written down, credentials that consumers still hold, and dependencies nobody inventoried. The cards below cover the failure modes we see most often and the checks that catch them before a consumer does.

Unmapped gateway scripts change behavior

API Connect assembly policies and gateway scripts often carry header rewrites, error handling and conditional routing that no one documents outside the code. When these are rebuilt as WSO2 mediation sequences, small differences in ordering, status codes or null handling change responses. Replay a sample of production traffic through both gateways and diff the responses, and run contract tests against each OpenAPI definition before cutover. Keep the API Connect gateway running so you can route traffic back if a diff appears.

Credentials and OAuth clients break consumers

Consumer keys, client secrets and OAuth clients issued in API Connect do not carry over automatically to WSO2 API Manager. Every consumer that holds a credential will fail with authentication errors on cutover unless a re-issue plan exists. Decide whether to re-issue credentials per application, run both sets in parallel for a defined window, and notify each consumer owner in advance. Test token validation against the new key manager before any traffic moves.

Plan and quota differences shift throttling

API Connect plans set rate limits and quotas per product, and WSO2 API Manager expresses throttling through its traffic manager and subscription policies. Limits that look equivalent on paper can reject calls at different thresholds or on different time windows. Export every plan's limits, map each to a WSO2 throttling policy, and load-test the mapped values against real consumer call patterns. Confirm with your platform team exactly how the traffic manager counts requests in your deployment.

Undocumented consumer dependencies surface late

Some consumers call APIs through hostnames, paths or headers that never appeared in a catalog, such as a batch job, a partner gateway or a legacy script. These dependencies only show up when they fail after cutover. Build a consumer inventory from API Connect consumer organizations and applications, then pull call logs for the past full business cycle and match each caller to an owner. Anything without an owner should block the move for that API.

Analytics history and dashboards go dark

Usage analytics, error rates and latency history in API Connect rarely map one to one to the metrics WSO2 API Manager emits. Teams often discover after cutover that SLA reports and chargeback figures have no source. Define the metrics that finance, security and API owners need, confirm which ones WSO2 API Manager exposes in your deployment, and export historical API Connect data before decommissioning. Keep a rollback path that includes the old analytics store until reporting is validated.

How the move differs by estate size and starting point

A small estate on SaaS API Connect usually has a limited number of products, a handful of consumer organizations and most traffic handled by a gateway that IBM operates. The inventory is short, so the main risk is missing something that exists only in the cloud console, such as plans, subscriptions or custom policies that were never exported. Gateway work is mostly a re-implementation of routing and security, because you will host WSO2 API Manager gateways yourself rather than inherit IBM's runtime. Cutover is typically a DNS or client endpoint change, applied per API and planned around consumers that hardcode hostnames.

  • Inventory: Export every API definition, product and plan from the SaaS console, and record which consumer organizations hold live keys.
  • Gateway work: Stand up a WSO2 gateway and move routing, authentication and rate limits, with the DataPower policy mapping handled on its own page.
  • Applications and credentials: Recreate applications in the WSO2 developer portal and re-issue credentials, then give each consumer a dated switch-over window.
  • Cutover: Move low-traffic APIs first and keep the SaaS gateway running in parallel until consumers confirm.
  • Subscription terms: Confirm your SaaS notice period and data retention terms with IBM before you plan the final shutdown.

Before you start, confirm with IBM and WSO2 which SaaS exports include analytics history and which must be recreated by hand.

Questions buyers ask before moving from API Connect to WSO2

How much effort does moving from API Connect to WSO2 API Manager take?

The effort depends mainly on how many APIs, products, plans and consumer applications you run, and how much of your API Connect logic lives in assembly policies and gateway scripts. A simple estate with OpenAPI definitions already in source control is a small job. An estate with heavy custom transformation, many DataPower-specific behaviors or undocumented consumer contracts takes much longer. Ask for an inventory of each API with its policies, gateway scripts, authentication method and consumer count before agreeing on effort. That inventory is the input that makes any quote meaningful.

How long does an API Connect to WSO2 migration typically take?

No duration is fixed by the product, so the timeline is set by your estate and your change process. The main drivers are the number of APIs and the complexity of their mediation, the number of consumer organizations that must re-register applications, how many environments you need to keep in parallel during cutover, and your security and change approval cycles. Run a pilot with a representative API and a low-risk consumer first, then use what you learn to plan the rest. Confirm the schedule with the vendor or implementation partner against a written scope.

What does the migration need from our own team?

Your team needs to supply knowledge that exists only inside your organization. That includes the owners of each API, the consumers who depend on them and the agreed behavior of each product plan. Platform engineers need access to the existing API Connect environment, the target Kubernetes or virtual machine infrastructure and identity systems. Security staff should review authentication, authorization and throttling decisions before cutover. Plan for named reviewers on both sides, because most delays come from unanswered questions about consumer contracts rather than from the technical conversion.

Can an internal team migrate from API Connect to WSO2 without a partner?

An internal team with strong Java, gateway and API lifecycle skills can do the work, and WSO2 API Manager is Apache-2.0 licensed, so the software itself is open to inspect and run. The practical question is capacity and experience. Mapping assembly policies to mediation, rebuilding a catalog, and re-onboarding consumers all require someone who has done it before. Many teams split the work: they keep API ownership and consumer communication in-house and bring in outside help for the platform build, hardening and cutover. DeployOpen plans, implements and hardens self-hosted platforms in your own infrastructure under a fixed scope agreed in writing, so you can decide which parts to keep internal.

Do we need a WSO2 subscription to use API Manager commercially?

WSO2 API Manager is Apache-2.0 licensed, but WSO2 describes a commercial subscription that adds expert support, continuous product updates, vulnerability monitoring and access to the licensed distribution for commercial use. Whether you need that subscription depends on whether you want vendor-backed support and patching, and whether your legal review accepts the open-source build for production use. Confirm the license terms for the exact release you plan to run, including the 4.7.0 release that was published on April 29, 2026, and ask WSO2 for the current subscription terms in writing before you budget.

Do our APIs and OpenAPI definitions transfer to WSO2 as they are?

OpenAPI definitions usually carry over as the starting point, because WSO2 API Manager supports REST, GraphQL and AsyncAPI APIs. However, the definition is only part of an API. Assembly policies, gateway scripts, rate limits, security schemes and error formats must be re-expressed as WSO2 mediation policies, and some behavior may have no direct equivalent. Export every definition, then compare the generated API in WSO2 against a test suite that captures current responses. Expect to review each policy by hand, and treat any behavior you cannot reproduce as a decision to make, not a silent gap.

What happens to existing API keys and consumer credentials?

Credentials do not move automatically between the two platforms, so each consumer application must be re-issued credentials in WSO2 after its subscription is recreated. Plan this as a coordinated cutover rather than an overnight switch. Options include running both gateways in parallel, giving consumers a dated window to rotate their secrets, and blocking old keys only after the last consumer confirms success. Confirm with your security team how client secrets are stored and rotated, and review whether any existing tokens need revocation. Consumer communication and a rollback plan should be written before the cutover date is set.

How DeployOpen works on this

DeployOpen plans, implements, integrates, hardens, backs up, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For a move from IBM API Connect to WSO2 API Manager, we start with a written scope that covers your APIs, products, plans, gateways and consumers before any work begins.

How we scope

  • Inventory every API Connect product, plan, API definition and consumer organization that must keep working after cutover.
  • Agree in writing which gateways, assembly policies and gateway scripts map to WSO2 mediation and which are retired.
  • Define the target deployment model, whether self-hosted on premises, on Kubernetes or hybrid, before any build starts.

How we build

  • Export OpenAPI definitions and rebuild catalog entries, subscription tiers and throttling policies in WSO2 API Manager.
  • Re-create authentication, rate limiting and transformation logic as WSO2 mediation sequences and custom policies, then test each against recorded traffic.
  • Migrate consumer organizations and applications, and plan how client credentials are re-issued with a dated switchover.

How we hand over

  • Deliver runbooks for deployment, configuration, backup and restore, and upgrades of the WSO2 API Manager environment.
  • Document the mapping from each API Connect artifact to its WSO2 equivalent, including gaps and the decisions behind them.
  • Walk your platform, security and API teams through the operating model and confirm acceptance against the written scope.

How we support

  • Ongoing support, upgrades and continuous security testing are available as a retainer after handover.
  • Ask whether your WSO2 subscription, if you buy one, covers the support and update channel you need, and confirm it with WSO2.
  • Confirm with your auditors which evidence they expect, since DeployOpen prepares controls and evidence but does not issue audit reports.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.