Migrate MuleSoft API management to WSO2 API Manager

A practical plan for moving MuleSoft API Manager policies, client applications, specifications and developer portal to self-hosted WSO2 API Manager, including what moves cleanly, what needs rework and what drives effort.

On this page

How to migrate MuleSoft API management to WSO2 API Manager

If a MuleSoft renewal, a licensing change, a residency requirement or lock-in has pushed you toward leaving, the API management half of that exit is a bounded project. It consists of four things: the API specifications, the policies attached to each API, the client applications that consume them, and the developer portal and gateway that expose them. Each can be inventoried, mapped and tested on its own, which is what makes the work plannable. Most teams do the work with a platform engineering group that owns the gateway and runtime, an API or product team that owns the specifications and consumer relationships, and a security team that signs off on authentication, throttling and logging. An implementation partner is often brought in for the gateway build, the migration tooling and the cutover runbook, but the inventory and the consumer conversations stay with the client.

Start with an inventory before any design work. For each API in Anypoint Exchange and API Manager, record the specification format (RAML or OAS), the policies applied, the tiers and SLAs promised to consumers, the client applications registered against it, and the base URLs in use. Then check what WSO2 API Manager needs in its place: the Publisher for API definitions, the Developer Portal for consumer onboarding, the gateway for routing, mediation and security, and the traffic manager for throttling. WSO2 API Manager is Apache-2.0 licensed, but WSO2 sells commercial subscriptions for expert support, continuous updates, vulnerability monitoring and the licensed distribution for commercial use. Confirm with WSO2 which of these your organization needs before you commit to a deployment model. Check the current release notes and the WSO2 API Manager 4.7.0 release for the JDK requirement, which the repository lists as JDK 21.

The main risk is client credentials and consumer behavior, not gateway configuration. Client applications registered in MuleSoft will not carry over automatically, so plan how each consumer receives new keys, how overlapping endpoints run during cutover, and who confirms that each consumer has switched. Test policy equivalence per API with replayed traffic in a non-production gateway, and keep a rollback route to the MuleSoft endpoint until the last consumer has moved. Ask any vendor or partner for a written list of which MuleSoft policies map to native WSO2 policies, which need custom mediation, and which are not covered, and treat that list as the scope baseline. Effort depends on the number of APIs, the policy complexity and the consumer count, so size it from your own inventory rather than from any generic estimate.

Which MuleSoft API Manager capabilities map to WSO2 API Manager

This table maps each Anypoint API Manager capability to its closest WSO2 API Manager counterpart and marks it as clean, needs rework or gap. Use it to scope the migration backlog, then confirm exact policy parity against the current vendor documentation in your own environment before committing to a cutover date.

Anypoint capabilityWSO2 API Manager counterpartMigration status and notes
API specifications and Exchange linksPublisher, with REST, GraphQL and AsyncAPI supportNeeds rework. Export RAML or OAS from Exchange, convert RAML to OpenAPI where needed, then re-import into Publisher and validate each definition.
Rate limiting and throttling policiesGateway policies and the traffic manager for throttlingNeeds rework. Map each SLA tier to a WSO2 throttling policy and confirm the counting scope (per application, subscription or resource) matches the original.
Authentication policies (client ID, OAuth2, JWT)Gateway security with OAuth2 and key-based access, extensible with custom authenticatorsNeeds rework. Basic patterns map cleanly, but custom Mule policies need a Java authenticator or policy rewrite.
Other policies (transformation, caching, IP allow lists)Gateway mediation policies and custom policy extensionsGap to confirm. Some Mule policies have no direct equivalent and must be rebuilt as custom mediation. Verify each against the vendor documentation.
Client applications and contractsApplications and subscriptions in the Developer Portal and PublisherNeeds rework. Recreate applications, credentials and subscriptions from an inventory, since exports of consumer contracts may not carry over.
Developer portalDeveloper Portal web interfaceNeeds rework. Rebuild API documentation, pages and branding; Exchange portal content is not moved automatically.
Analytics and monitoringAnalytics and monitoring provided by the API Manager deployment, plus your own observability stackGap to confirm. Dashboards and alert history do not transfer. Plan external metrics and logging before cutover.
Gateway deployment (CloudHub or Runtime Fabric)Self-hosted gateway on premises, Kubernetes, or hybrid with a SaaS control planeClean for self-hosting. You own the gateway runtime, upgrades and capacity, so define the operating model first.

What data and integrations move, and what you rebuild

A MuleSoft API management exit moves some assets as files, some as configuration you re-enter, and some not at all. The cards below separate specifications, consumer credentials, portal content and backend services so that each one gets an owner and a check before cutover.

API specifications from Exchange

RAML and OAS (OpenAPI) specifications exported from Anypoint Exchange become the input for WSO2 API Manager's Publisher, which accepts REST, GraphQL and AsyncAPI definitions. Treat the exported file as a starting point: confirm it validates, that examples and security schemes survived export, and that the spec matches what the running Mule application actually serves. Specs without a download must be rebuilt by hand.

WSDL and AsyncAPI definitions

SOAP services described by WSDL and event APIs described by AsyncAPI need a separate check because the Publisher's handling differs from REST. WSDL-based services may need the gateway's SOAP mediation rather than a plain REST route, and AsyncAPI definitions must be confirmed against the message broker and channels actually in use. Ask the implementation team to test each non-REST API end to end before it is listed as migrated.

Client credentials and subscriptions

Consumer applications, their client IDs and secrets, and their subscriptions to API tiers do not carry over as a usable set. Plan to re-issue credentials in WSO2 API Manager, then coordinate with each consumer team on the cutover window, secret rotation and the date old MuleSoft credentials stop working. Keep a register that maps each MuleSoft client application to its WSO2 application and owner.

Policies and throttling tiers

API Manager policies, rate limits and SLA tiers must be recreated in WSO2's Publisher and traffic manager, and their behavior verified against the MuleSoft originals. Export the policy configuration from Anypoint, map each policy to a WSO2 equivalent or a custom policy, and record any gap. Confirm that throttling counters and quotas match what consumers were promised before switching traffic.

Developer portal content

Portal pages, getting-started guides, tutorials and examples published on the MuleSoft Developer Portal are generally not exported as a set. Copy the content you need, rebuild the layout in WSO2's Developer Portal, and check that links, code samples and images still resolve. Assign an owner for each page so that documentation does not go stale after the portal goes live.

Backend integration services

The gateway does not replace the integrations behind it. Mule applications, or their Apache Camel successors, remain the backends that WSO2's gateway routes to, so the endpoints, TLS settings, authentication to each backend and timeouts must be re-pointed and retested. Map each published API to the service that implements it, and confirm which backends will move first and which will stay on MuleSoft during a transition period.

Running the WSO2 gateway in front of your integration services

The WSO2 gateway is the runtime that receives client traffic, routes it to the back-end services, applies mediation and enforces security, so it is the piece that replaces MuleSoft's API Manager enforcement point for your Mule or Camel services. Start by inventorying every API that currently sits behind an API Manager policy chain and mapping each policy (authentication, header or payload transformation, IP filtering, caching, logging) to a gateway mediation or security step. Where a policy has no direct equivalent, plan a custom mediator or extension in the gateway rather than moving that logic into the service itself. Confirm in a proof of concept that the back ends, including any Mule applications still running on CloudHub, Runtime Fabric or your own servers, accept the gateway's outbound calls and certificates unchanged.

Throttling belongs to the traffic manager, which the WSO2 repository describes as the component that handles throttling. Recreate each tier and quota from MuleSoft's rate limit and SLA tier policies as a WSO2 throttling policy, then test it under load, because a tier that looks correct in configuration can still behave differently under concurrent traffic. A control plane can also manage WSO2 gateways alongside third-party gateways, and WSO2 states that this includes Kong, AWS, Azure and Envoy. Treat that as a vendor statement to verify in your environment, and confirm which of your existing gateways, if any, you intend to keep during the transition.

Deployment is the decision with the largest effect on your network and data residency posture. WSO2 supports API Manager on premises from extracted packages, on Kubernetes through the separate WSO2 API Platform for Kubernetes, as a hybrid model with a SaaS control plane and gateways on premises, and as a fully managed SaaS with a 99.95% SLA that WSO2 publishes on its API Manager page. Only the first two keep every component, including the control plane, inside your boundary. Ask WSO2 which control plane data, logs and analytics leave your network under the hybrid and managed options, and have your security and compliance teams approve that answer before you pick a model. Use WSO2's API Manager 4.7.0 release notes and build requirements (JDK 21) to size your build pipeline.

Migration sequence from inventory to decommission

This sequence moves MuleSoft-managed APIs, consumers and policies to WSO2 API Manager in controlled stages, so each consumer changes over only after its behavior has been verified. Each step ends with a written output that the next step depends on.

  1. Inventory APIs, consumers and policies

    The API owner and platform team list every API managed in Anypoint API Manager, its specification source in Anypoint Exchange, its gateway and environment, every client application subscribed to it, and every policy attached to it, such as rate limits, client ID enforcement and JWT validation. Include APIs that have no formal owner, since they are often the ones nobody has documented. Consumer contact details and expected call volumes go in the same register. The output is an inventory register with one row per API and per subscription, reviewed and signed off by the API owners. Do not start any build work until every API in the register has an owner and a specification file stored in Git.

  2. Export specifications and recreate policies in WSO2

    Export each API's RAML or OAS specification from Anypoint Exchange and confirm it validates before import. Publish the specification in WSO2 API Manager Publisher, then recreate each MuleSoft policy as the equivalent WSO2 gateway policy or custom mediation, documenting any policy that has no direct match. Recreate the client applications and their subscription tiers in the Developer Portal so consumers can obtain credentials. The output is a configuration baseline in version control and a gap list of policies that need custom work or a design decision. Mark any policy you cannot map as a blocker for the pilot.

  3. Run a pilot with a non-critical consumer

    Select one API with low business impact and one consumer team willing to test. Point that consumer at the WSO2 gateway in a non-production environment, then compare response codes, payload shapes, latency, throttling behavior and error messages against the MuleSoft baseline using the same test requests. The consumer team confirms the credentials, subscription and portal workflow work for their developers. The output is a pilot report listing each difference, its cause and whether it is accepted, fixed or blocking. Repeat the pilot if the report contains unresolved blocking differences.

  4. Run both gateways in parallel

    Keep the MuleSoft gateway serving production traffic while the WSO2 gateway receives copies of selected requests, or serves a small share of traffic through DNS or a routing layer you control. Monitor errors, latency, authentication failures and throttling counts on both paths and compare them in one dashboard. Confirm that the WSO2 gateway can reach the backend integration services, including any Mule runtimes that remain in place, with the same network and certificate arrangements. The output is a parallel run log showing agreed thresholds and the period in which they held, with a named owner who can stop the traffic shift.

  5. Cut over consumers in stages

    Move consumers to the WSO2 gateway in groups, starting with the lowest-risk and ending with the most critical. For each group, the runbook records the DNS or endpoint change, the credential rotation, the rollback command or configuration, the contact for each consumer, and the check that confirms success. Consumers that hardcode the MuleSoft host or depend on MuleSoft-specific headers are handled before their group moves. The output is a cutover runbook with a completed sign-off for each group. If a group fails its check, traffic returns to MuleSoft using the documented rollback before the next group is attempted.

  6. Decommission Anypoint API Manager and collect evidence

    Once every consumer uses the WSO2 gateway and the rollback window has closed, disable the MuleSoft API proxies, revoke remaining client credentials, and export final logs and audit records that your retention policy requires. Remove the Anypoint API Manager configuration only after its exports are verified and stored. Confirm the licensing position with your MuleSoft account team before ending the subscription, since contract terms govern the notice period. The output is decommission evidence: the final inventory register, the cutover sign-offs, the revocation records and the archived configuration, kept with the owners of the compliance controls that depend on them.

How the migration differs by estate size and starting point

When a small set of APIs is fronted by CloudHub or CloudHub 2.0, MuleSoft operates the runtime and often the gateway that enforces policies, so the migration is mainly about moving the management layer. The main work is exporting specifications, rebuilding policies in WSO2 API Manager, and pointing the existing traffic at a WSO2 gateway that you run. Because CloudHub is a MuleSoft-managed environment, the gateway you stand up is new infrastructure in your own cloud account or data center, and you own its patching and scaling from day one.

  • Consumer coordination: Identify every client application registered in Anypoint and confirm who owns its credentials, so you can issue new keys in WSO2 before any endpoint changes.
  • Network placement: Decide whether the WSO2 gateway sits in front of CloudHub-hosted backends or whether those backends move to your network first, since the gateway needs a route to them.
  • Gateway count: A small estate often needs one WSO2 gateway environment for production and one for testing, which keeps the footprint simple.
  • Policy rebuild: Recreate each policy by hand, since few CloudHub estates have enough policies to justify automation.
  • Cutover: Run both paths in parallel for a short window and shift consumers in batches.

Confirm with MuleSoft which Anypoint assets you can export from your organization, and check which policies you actually enforce today.

What drives the cost and duration of this migration

This table lists the main drivers that change the effort and cost of moving MuleSoft API management to WSO2 API Manager, with the cost component each one affects. Read it as a checklist for scoping: each row shows whether the cost is one-time or recurring and what to request in a written quote.

DriverCost component and who paysOne-time or recurringWhat to ask for in a written quote
Number of APIs and policy variantsImplementation labor for mapping each API, policy and environment-specific setting to WSO2 policiesOne-time, scales with countPer-API effort estimate, list of policy variants, and assumptions about shared policy templates
Client applications and partner consumersInternal staff time to recreate applications, credentials and subscriptions, and to coordinate partner credential changesOne-time, with ongoing partner support during cutoverPlan for consumer notification, credential rotation, and who runs partner onboarding
Custom policies or authenticatorsEngineering time to rewrite Mule-specific logic in WSO2's extension model (custom authenticators, policies and workflows)One-time, plus maintenance of custom codeInventory of custom logic, rewrite approach, test coverage, and who maintains the extensions after handover
Developer portal branding and contentDesign, content migration and review by internal teams; optional implementation supportOne-time, with recurring content upkeepScope of theme work, page inventory, and whether documentation is migrated or rewritten
Deployment targetInfrastructure for self-hosted, hybrid or Kubernetes deployment, plus platform operations staffInfrastructure recurs; setup is one-timeSizing assumptions, high-availability design, and which components run in your own cloud or data center
WSO2 subscription for support and updatesOptional annual commercial subscription that includes expert support, continuous updates, vulnerability monitoring and a licensed distribution for commercial useRecurring, if chosenSubscription tier, included support hours or response terms, and what the subscription covers for your deployment model
Parallel-run lengthDuplicate infrastructure and staff time while MuleSoft and WSO2 gateways both serve trafficRecurring for the length of the overlapPlanned overlap period, traffic routing method, rollback plan, and the exit date for MuleSoft API Manager

Questions buyers ask before moving MuleSoft API Manager to WSO2

How long does a MuleSoft API Manager move to WSO2 take?

The duration depends mainly on how many APIs, policies and client applications you run, and how many of them carry custom Groovy or DataWeave logic that must be rewritten. No public timeline for this migration is supplied here, so ask any implementation partner to base its estimate on an inventory of your APIs, policies and consumers. Plan for a parallel period in which the WSO2 gateway and the Anypoint gateway both route traffic, since that overlap sets much of the calendar. Confirm the sequencing with your own change management team before accepting a date.

Can our own team migrate MuleSoft API Manager to WSO2 without a partner?

Yes, a team with API gateway and Java experience can do it, provided it has time and a clear inventory. WSO2 API Manager is Apache-2.0 licensed, so the software itself carries no license fee for in-house use. Your team would need to export specifications, recreate policies, configure applications and subscriptions in the Publisher and Developer Portal, and operate the gateway. Consider whether that work competes with your production roadmap. A partner can take over fixed-scope pieces, such as the policy mapping or the cutover runbook, while your staff keep ownership.

What skills and staff time does the WSO2 API Manager work require?

The work needs people who understand REST and GraphQL API design, OAuth 2.0 and API keys, gateway policies, and container or Linux operations. WSO2 API Manager 4.7.0 builds with JDK 21, so the build pipeline and any custom extensions must support that version. Expect the API owners to validate their own specifications, and the security team to review authentication and throttling settings. Your engineers will also need to learn the Publisher and Developer Portal workflows. Confirm the headcount and skill mix with a written plan before the project starts.

Do we need a WSO2 subscription to run API Manager?

No. WSO2 API Manager is Apache-2.0 licensed, so you can run the product without a commercial subscription. WSO2 sells on-premises subscriptions that add expert support, continuous product updates, vulnerability monitoring and access to a licensed distribution for commercial use. Those items are optional, but a regulated organization should decide early who will patch the platform, monitor advisories and answer incidents. If you skip the subscription, budget for internal or partner staff to cover those duties. Ask WSO2 to confirm current subscription terms directly.

Will API consumers have to change their credentials after the move?

It depends on how you design the cutover. Client applications are represented as applications and subscriptions in WSO2 API Manager, so consumers whose credentials are not recreated in the new system will need new keys or tokens. Many teams avoid a forced change by keeping the same token issuer and recreating subscriptions behind the scenes, then routing traffic gradually. Map every MuleSoft client application to a WSO2 application before cutover, and test that existing tokens are accepted or rejected as intended. Agree on a notice period with each consumer team.

What does a DeployOpen fixed-scope engagement cover for this migration?

DeployOpen plans, implements, customizes, integrates, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure. For this migration, a fixed-scope engagement could cover the inventory of MuleSoft assets, the WSO2 deployment in your environment, policy and application recreation, the gateway configuration in front of your integration services, and the cutover documentation. Scope, deliverables and timelines are agreed in writing before work starts, and a quote follows from that written scope. Ongoing support, upgrades and continuous testing are available as retainers. DeployOpen does not issue audit reports or certifications.

Which MuleSoft API Manager features may not have a direct WSO2 equivalent?

Start with a feature-by-feature inventory rather than assuming parity. WSO2 API Manager provides a gateway for routing, mediation and security, a traffic manager for throttling, a Publisher, a Developer Portal and support for REST, GraphQL and AsyncAPI. It can be extended with custom authenticators, policies and workflows. Custom MuleSoft policies, analytics dashboards and some Exchange-based workflows will need a design decision: rebuild, extend or retire. Confirm each policy and its behavior against WSO2 documentation in a proof of concept before committing.

What usually goes wrong in an API management exit and how to prevent it

Most API management exits fail at the edges: policies that behave differently, consumers that hold old credentials, and traffic that never passed through the gateway. The cards below cover the failure points that recur when moving MuleSoft API Manager workloads to WSO2 API Manager, with a prevention step for each.

Unmapped policies change behavior

A policy that has no direct equivalent in WSO2 API Manager often gets dropped or approximated during the rebuild, and the API then answers differently under load or with bad input. Export each policy attached to each API in Anypoint, list its order and parameters, and map it to a WSO2 mediation sequence, throttling policy or custom extension before cutover. Treat every unmapped entry as an open decision, and test it with recorded requests from production traffic. Document each approximation as a known difference.

Consumers break on new credentials

When the gateway, client IDs, client secrets or token endpoints change, every consumer application that stored the old values stops working on the day of cutover. Inventory every registered application in Anypoint, record which APIs each one calls and which credential type it uses, and create the matching applications and subscriptions in WSO2 API Manager ahead of time. Plan a window in which old and new credentials are both accepted, and confirm with each owner which secret they will rotate and when.

Missed partner-facing contracts

Some APIs carry commitments to external partners, such as a published endpoint address, an agreed rate limit or a response format that a partner's system parses. These commitments often live in contracts or emails rather than in the API specification, so they are easy to overlook in a technical inventory. Ask business owners to list every external party that receives traffic, and compare each agreed behavior with the new configuration. Get written sign-off from partners before changing any address they depend on.

Developer portal content loss

Anypoint Exchange holds specifications, examples, descriptions and sometimes tutorial pages that developers rely on, and a new portal can launch with empty or outdated content. Export specifications in RAML or OAS format and confirm which assets allow download, since some may not. Rebuild the portal's API descriptions, usage examples and getting-started pages in WSO2 Developer Portal, then have API owners review each page against the live behavior before publishing.

Throttling mismatches during parallel run

Running both gateways side by side can double the effective quota a consumer receives, or split one consumer's traffic so that neither gateway sees the full volume and limits never trigger. Define limits per application and per API in WSO2 Traffic Manager to match the MuleSoft tiers, and decide whether counters are shared or separate during the parallel run. Verify with a test client that exceeds the limit on each gateway, and record which behavior the business accepts before moving traffic.

Direct calls that bypass the gateway

Some services are called directly by internal teams, batch jobs or other back-end systems, skipping the gateway entirely, so changing the gateway does not move them and they are never governed by its policies. Compare access logs and network flows against the gateway's routes to identify callers that never appear there, and restrict backend network access so that traffic must pass through the gateway. Confirm each direct caller with its owner and decide whether to route it through WSO2 or document a justified exception.

How DeployOpen scopes, runs and supports the migration

DeployOpen plans, implements, customizes, integrates, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure. For this move, we treat the MuleSoft API management exit as a fixed-scope engagement that runs WSO2 API Manager in your environment, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

  • Inventory every API managed in Anypoint API Manager, with its specification, version, policies and consuming client applications
  • Agree in writing which APIs, developer portal content and gateway routes move in the first phase
  • Confirm whether your MuleSoft deployment uses CloudHub, Runtime Fabric or on-premises Mule servers before design starts
  • Ask for a quote that itemizes the specification export, policy recreation, portal setup and gateway deployment separately

How we build

  • Deploy WSO2 API Manager 4.7.0 in your infrastructure, noting that the repository says building it requires JDK 21
  • Recreate Anypoint policies as WSO2 gateway policies, flagging any MuleSoft policy with no direct equivalent for a design decision
  • Rebuild client applications, subscription tiers and throttling in the traffic manager and test each against a staging gateway
  • Place the WSO2 gateway in front of the integration services and verify routing, authentication and error handling end to end

How we hand over

  • Document the deployment topology, configuration, policy mapping and runbooks for your operations team
  • Provide a test record showing which APIs, clients and policies were verified and which remain open
  • Set up backup and upgrade procedures for the API Manager databases and gateway configuration
  • Hand over the developer portal content and publisher workflows so your teams can maintain them without DeployOpen

How we support

  • Offer ongoing support, upgrades and continuous testing as a retainer after the initial cutover
  • Agree the support boundary in writing, covering which components and environments are included
  • Coordinate with WSO2 if you choose a commercial subscription for expert support and vulnerability monitoring, which WSO2 sells separately
  • Schedule periodic security testing of the gateway and APIs as part of the retainer where your risk profile requires it

Sources and further reading

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.