Migrate from Azure API Management to WSO2 API Manager: what the move involves
Moving from Azure API Management to WSO2 API Manager is a staged program, not a configuration copy. If your renewal, data residency requirement or lock-in concern has pushed you to look at alternatives, plan for parallel running, API-by-API cutover and a period in which developers, applications and credentials exist in two places. The work is usually led by a platform team with the API owners, and many organizations bring in an implementation partner for the control plane, gateway deployment and developer portal, since those are the parts that must be hardened and integrated with identity and logging in your own environment.
Start with an inventory of consumers, not just APIs. Each API has an owner, a set of products or tiers, subscriptions, keys and developer accounts, and some consumers are partners who will notice any change. WSO2 API Manager is licensed under Apache-2.0 and bundles a gateway for routing, mediation and security, a traffic manager for throttling, and Publisher and Developer Portal web interfaces. The platform team should confirm which of these pieces it will run, where each one is hosted, and how the Publisher and Developer Portal will be secured. Commercial subscriptions from WSO2 provide expert support, continuous product updates, vulnerability monitoring and access to the licensed distribution for commercial use, so ask WSO2 which of these your organization needs before you commit to a support model.
Plan the effort and risk around the portal and credentials. Importing OpenAPI definitions is the easier step. Re-creating products as API products and subscription tiers, moving developer accounts and applications, and re-issuing credentials require agreed cutover windows and consumer communication. Ask for a written scope that names the APIs in each wave, the rollback path for each wave, and how consumers will be notified. Before you start, confirm the exact WSO2 API Manager version you will deploy, since the current release, 4.7.0, requires JDK 21 to build from source.
Which Azure API Management capabilities map cleanly to WSO2 API Manager
This table maps each Azure API Management capability in your program to its closest WSO2 API Manager equivalent and marks it clean, needs rework or gap. Use it to scope the migration work, not as proof of feature parity. Policy-level behavior and portal customization must be confirmed against WSO2's documentation for the version you plan to run.
| Azure API Management capability | WSO2 API Manager equivalent | Status and what to confirm |
|---|---|---|
| APIs and operations | APIs published in the Publisher, with REST, GraphQL and AsyncAPI support | Clean for REST and GraphQL definitions. Confirm how your OpenAPI files import and whether operation-level settings carry over. |
| Products and subscriptions | API products in the Publisher with subscription tiers applied to them | Needs rework. Products must be rebuilt as API products, and each tier must be defined again with its own throttling. |
| Named values | Configuration held in deployment files and environment-specific settings, with no direct one-to-one object | Needs rework. Map each named value to a config key or secret store entry and confirm how it is referenced in mediation. |
| Policies: rate limiting | Traffic manager throttling policies at application, subscription and API levels | Needs rework. Confirm that your limit windows, keys and burst behavior match the throttling model in your version. |
| Policies: JWT validation | Custom authenticators and built-in OAuth2 and JWT handling at the gateway | Needs rework. Confirm issuer, audience and claim mapping against your identity provider, since Entra ID claims differ from defaults. |
| Policies: transformation | Mediation sequences and custom policies extended in Java | Gap for complex XML policy logic. Expect to rewrite transformations as mediation code and test each one. |
| Developer portal content | Developer Portal with customizable pages and API documentation | Needs rework. Confirm which content, themes and custom pages can be exported, and rebuild the rest by hand. |
| Developer accounts and applications | Developer Portal user and application records | Gap for direct export of password hashes. Plan for re-registration or a supervised import, and confirm with WSO2 what your version supports. |
| Diagnostics and analytics | Analytics through the platform's observability components, configured separately | Needs rework. Rebuild dashboards and alerts in your own monitoring stack and confirm retention settings. |
| Self-hosted gateway | Gateway deployable on premises, on Kubernetes or as a managed cloud service | Clean for on-premises and Kubernetes. Confirm the connectivity model between a SaaS control plane and on-premises gateways if you use hybrid mode. |
What data and integrations to export, re-create and rebuild
A move from Azure API Management to WSO2 API Manager splits into four kinds of work: definitions that can be imported, configuration that must be mapped by hand, records tied to people and credentials, and connections to systems outside the gateway. Treat each group as a separate workstream with its own owner and check, and confirm export tooling against current Azure and WSO2 documentation before you rely on it.
OpenAPI definitions as the import path
OpenAPI definitions are the primary import path. Export each API's definition from Azure API Management and load it into WSO2 API Manager's Publisher to create the API shell, resources and schemas. WSO2 also supports REST, GraphQL and AsyncAPI, so check that every API in your inventory maps to a supported type, especially SOAP or event-driven APIs that may need separate handling. Confirm which definition version Azure returns for each API, because stale or partial specs are the most common source of rework.
Products and subscription configuration
Azure products group APIs and attach subscription rules, rate limits and approval settings. In WSO2 these become API products and subscription tiers, which are configured in the Publisher rather than imported automatically. Export the product-to-API mapping, subscription approval mode and any quota values from the Azure management interfaces, then build a table that maps each Azure product to a WSO2 product and tier. Confirm with WSO2 documentation which of these settings carry over through any import tooling and which must be recreated manually.
Developer accounts and applications
Developer accounts and the applications they created hold the consumer relationships that the migration must preserve. Export the developer list, their registered applications and their subscription links from Azure, and decide whether accounts move as-is or are re-invited. Migrating user records usually means password hashes and login methods do not transfer, so plan for users to set new credentials. Ask WSO2 which identity store the developer portal will use and whether account data can be bulk loaded without a manual step per consumer.
Named values and secrets handled separately
Named values in Azure often hold backend URLs, keys and certificate references used by policies. Do not export secret values into the migration inventory or shared spreadsheets. Record each named value's name, purpose and the APIs that reference it, then load secrets into a secrets manager or WSO2 configuration with restricted access. Confirm how Azure returns secret values through its management interfaces, since some are write-only, and tell the security team which secrets will be rotated during cutover.
Backend integrations to rebuild
Backends, mediation policies and transformations that Azure runs through policy XML do not become WSO2 configuration automatically. Inventory every backend target, its authentication method and each set-header, rewrite-uri or send-request step, then rebuild those behaviors as WSO2 mediation sequences or custom policies. Test each backend connection from the new gateway before any DNS change, and keep the Azure configuration unchanged until each rebuilt route passes.
Identity provider connections to re-register
Any Entra ID or other OAuth connection that Azure uses for developer sign-in or API authorization must be re-registered for WSO2 API Manager. Each identity provider needs new redirect URIs, client registrations and token audience settings that point at the WSO2 hosts. Record which Azure AD application each API trusts, then confirm with WSO2 how it validates tokens from external issuers and how key manager configuration is set up. Test token validation for every client type before cutover.
How to sequence the migration from inventory to decommission
This sequence moves one API product at a time from Azure API Management to WSO2 API Manager, so each stage produces a checked record before the next begins. The end state is a WSO2 deployment serving all consumers and an Azure instance decommissioned with evidence kept on file.
Inventory APIs, consumers and policies
Export every API, its policy XML, products, subscriptions, named values and developer accounts from the Azure instance, and record which consumers call which API and how often. The platform team owns the technical export, and the API product owners confirm the business list. Done means one inventory document lists each API with its backend, authentication method, policies, product, subscribers and owner, and every gap is assigned to someone. Use the export guidance in the related how-to page before you start.
Map policies to WSO2 mediation and throttling
For each Azure policy, decide whether WSO2 API Manager covers it with built-in gateway mediation, traffic management for throttling, a custom authenticator or policy extension, or whether it must be redesigned in the backend. Confirm the target behavior for JWT validation, rate limits and header transformations in a test environment, not from documentation alone. The output is a policy mapping sheet with one row per Azure policy, its WSO2 equivalent and a named owner for each gap.
Build a pilot on WSO2 API Manager 4.7.0
Choose one API product with a small, willing consumer group and stand up WSO2 API Manager 4.7.0, released on April 29, 2026. The repository notes that building from source requires JDK 21, so confirm the JDK in your build pipeline and in the runtime image before you start. Import the OpenAPI definition, re-create the product as an API product with its subscription tiers, and run the pilot in a non-production environment. The output is a pilot runbook with install steps, configuration values, test cases and rollback steps.
Run the pilot with a small consumer group
Move the pilot consumers onto the WSO2 gateway with new application registrations and test credentials, and compare response codes, latency and throttling behavior with the Azure baseline. Record every defect, including any consumer that relied on an Azure-specific header or behavior. The pilot is complete when the test cases pass, the agreed consumers have made production-representative calls, and the owners have signed off the runbook. Record the findings in the runbook so the next waves reuse them.
Split traffic API by API in parallel
For each subsequent API product, run Azure and WSO2 in parallel and move traffic by changing DNS or gateway routing one API at a time, starting with the lowest-risk APIs. Keep the previous routing setting so you can revert quickly. The traffic split record lists each API, the date and time of each switch, the percentage or share of traffic routed to each platform where your routing method supports it, and the monitoring results observed after each change.
Re-issue credentials and cut over
Migrate developer accounts and applications, then issue new keys or tokens in WSO2 for each consumer and give them a fixed window to switch. Azure subscription keys cannot be assumed to carry over, so plan a notice to each consumer and confirm their onboarding steps with the developer portal. The cutover checklist covers consumer notices, new credential delivery, revocation dates for old keys, monitoring owners and the rollback contact. An API is cut over only when its checklist is signed off and no traffic reaches Azure for it.
Decommission the Azure instance with evidence
After every API has been cut over and the old keys are revoked, confirm with your logs that no traffic still reaches the Azure gateway, then remove the instance and its dependent resources such as custom domains, certificates and diagnostics. Confirm with your cloud and finance teams which resources bill after deletion and which recurring charges stop. Keep the decommission evidence: the final traffic logs, the deletion records, the exported configuration archive and the signed-off checklists, stored according to your retention policy.
What drives migration cost and duration, and how to keep each under control
This table lists each component that moves the cost and calendar of a move from Azure API Management to WSO2 API Manager, who is paid for it, and how to keep it contained. Read the first column as a checklist to size your own inventory before asking any partner for a written scope. No prices or durations are given here because none were supplied for this comparison.
| Cost component | What drives it | One-time or recurring | How to keep it under control |
|---|---|---|---|
| Number of APIs and versions | Each API, each live version and each backend it calls must be imported, mapped to a WSO2 API definition and tested through the gateway. | One-time | Inventory APIs and retire unused versions before export. Ask for the count of APIs and versions in the written scope. |
| Products and subscription tiers | Azure products bundle APIs and subscription rules. Each product must be re-created as a WSO2 API product with matching throttling tiers. | One-time | Map products to tiers in a spreadsheet first. Consolidate overlapping products so fewer tiers need rebuilding. |
| Developer accounts and applications | Each developer account, application and subscription key must be migrated or re-issued, and consumers must be told when credentials change. | One-time, plus support load during cutover | Decide early whether keys are re-issued or carried over. Ask the provider how many developer accounts are in scope and how notices will be sent. |
| Policy complexity | Inbound, outbound and backend policy XML, named values and custom expressions must be translated into WSO2 mediation sequences or extensions. Custom policies cost the most. | One-time | Classify policies as simple, mediated or custom. Ask for a policy-by-policy mapping in the quote. |
| Identity integration | Moving from Entra ID or other identity providers to WSO2 key manager, token issuance and scopes affects every client and gateway. | One-time, with ongoing identity operations | Confirm which identity provider stays in place and how scopes map. Test token flows with a pilot consumer. |
| Hosting and Kubernetes or VM operations | WSO2 API Manager runs on premises from extracted packages, as a managed cloud service, or on Kubernetes through WSO2 API Platform for Kubernetes. Each option carries its own build, patching and monitoring work. | Recurring | Choose one deployment model for the pilot. Ask for the hosting topology, environments and who patches them. |
| Support subscription choice | WSO2 sells commercial subscriptions with expert support, continuous updates, vulnerability monitoring and a licensed distribution for commercial use. The Apache-2.0 source is free, but support terms differ. | Recurring | Compare the open-source self-support path with a subscription in writing. Confirm which release line and update channel each option covers. |
| Internal team time | Platform engineers, API owners and security reviewers spend time on mapping, testing, cutover and training. This is usually the largest unseen cost. | One-time for migration, recurring for operations | Name the owners for each product and API group. Ask for a schedule that shows which work the internal team does and which the provider does. |
How the move differs for a small API catalog versus a large partner program
A single team with a few dozen APIs and an internal developer portal can usually move in one controlled wave. The consumers are known, they sit inside the organization, and a short coordination window with each owning team is often enough. The main work is the import and the rebuild of products, so most of the effort lands in the publisher configuration rather than in consumer communication.
- Sequencing: Import the OpenAPI definitions first, then rebuild products and subscription tiers for the whole catalog, and cut over in a single window if owners agree.
- Credentials: Re-issue keys to each internal application owner directly, and record which applications are still calling the old gateway before switching DNS.
- Testing: Run contract tests against the WSO2 gateway for each API and confirm that rate limits and JWT validation behave as the policies did in Azure.
- Portal: Migrate the small set of developer accounts by hand or with a short script, and confirm that internal sign-in is wired to the same identity provider.
- Rollback: Keep the Azure instance running until every owner confirms their traffic.
Confirm with your platform team which identity provider and internal network paths the catalog depends on before you schedule the window.
A program with many external partner consumers and a public developer portal changes the work more than the technology. Each partner has its own release calendar, its own integration tests, and its own tolerance for a changed hostname or key. Developer accounts, subscriptions and application registrations have to move without losing partner history, and partners often need notice before anything changes on their side.
- Sequencing: Migrate in cohorts, starting with low-volume partners on a parallel gateway, and keep DNS or routing changes per API so one partner's problem does not hold up the rest.
- Credentials: Plan a dual-running period where old and new keys both work, and agree the retirement date for Azure keys with each partner in writing.
- Testing: Ask each partner for a test environment or a sandbox key on WSO2 well before their cohort, and test throttling tiers against their real call patterns.
- Portal: Decide whether developer accounts, applications and subscriptions are imported or re-registered, and confirm the password and consent handling with your identity and privacy teams.
- Communication: Publish the change calendar in the public portal and track each partner's acknowledgment.
Confirm the contractual notice terms for each partner and whether any agreement names the gateway hostname or the Azure service.
In a regulated environment, the move is shaped by where the platform may run and by how evidence of the change is kept. WSO2 API Manager can be self-hosted from extracted packages or run on Kubernetes through the separate WSO2 API Platform for Kubernetes, so the target can sit inside an on-premises or isolated network. Installation, identity integration and every credential change then fall under the organization's own change and access controls.
- Sequencing: Build the on-premises control plane and gateways, complete hardening and backup tests, and only then start importing APIs, since the platform needs to be approved before consumers move.
- Credentials: Issue new credentials through the organization's approved secrets and identity processes, and log each re-issuance as evidence for the assessor.
- Testing: Include security testing of the gateway and developer portal in the target environment, and keep test results with the change record.
- Build: Confirm the JDK 21 requirement for the release you deploy and plan the build from a controlled, internal source.
- Connectivity: Verify that any hybrid design with a SaaS control plane is acceptable to your policy, because an air-gapped deployment cannot use it.
Confirm with your compliance lead which controls the assessor expects to see and whether the managed SaaS option is permitted at all.
What usually goes wrong when consumers move to new credentials
Moving consumers from Azure API Management subscription keys to WSO2 API Manager applications and tokens breaks in predictable places. The cards below cover credentials, policy behavior, developer data, portal content, identity configuration and capacity, and each one names a check to run before consumers cut over.
Broken consumer keys after re-issuance
Azure API Management clients send an Ocp-Apim-Subscription-Key header, and WSO2 API Manager issues OAuth2 tokens against applications and subscriptions. Any consumer that hardcoded the old key, or stored it in a config file or secrets vault, fails on the first call after cutover. Inventory every consumer that calls the old gateway by key owner, not only by API. Prevention: run a parallel period where old and new credentials both work on the same API, and track calls still using the old key before you revoke it.
Policy behavior that shifts rate limits
Azure API Management rate-limit and quota policies are scoped by key, product or IP, and their counting windows do not map one-to-one onto WSO2 traffic manager throttling tiers. A consumer that stayed within its quota in Azure can be throttled on day one in WSO2, or the reverse. Illustrative example: a 1,000 calls per hour quota that counts per subscription may need to be split into an application-level and an API-level limit. Prevention: replay production traffic profiles against a staging gateway and compare throttle responses before cutover.
Transformations that behave differently
Policies that rewrite headers, bodies or JSON to XML, or that set backend-specific values, are re-expressed as WSO2 mediation sequences and extensions. Edge cases such as null handling, content-type negotiation, and error body formats can change without any visible change in the OpenAPI definition. Consumers that parse error messages will notice first. Prevention: capture request and response pairs from Azure API Management diagnostics for each transformed operation, then diff them against WSO2 output for the same inputs.
Developer accounts and applications that do not migrate cleanly
Developer accounts, application registrations, subscription owners and their contact details live in the Azure developer portal store, and the export does not guarantee a one-to-one import into WSO2 Developer Portal. Applications can end up attached to the wrong owner, or to no owner at all, which blocks key rotation requests later. Prevention: export the developer and subscription list first, match each account to a verified owner, and assign applications to a named responsible person before the cutover date.
Portal content drift
Documentation pages, sign-up instructions, product descriptions and code samples in the Azure developer portal often describe the old keys, base URLs and sign-in flow. If the WSO2 Developer Portal is published with copied text that was never updated, consumers follow instructions that no longer work. Prevention: give each API a documentation owner, rewrite every snippet that shows a subscription key or base URL, and confirm each example with a test call against the new gateway.
Identity provider misconfiguration
WSO2 API Manager issues tokens through its own key manager, and it must trust the identity provider that consumers authenticate against, which may be Microsoft Entra ID in Azure. Wrong issuer URLs, audience values, scopes, JWKS endpoints or clock settings cause token rejection that looks like an authorization failure. Prevention: validate a token from each identity provider against every API in staging, and confirm the issuer, audience and scope claims match what the gateway expects. Check the WSO2 documentation for the supported key manager configuration.
Gateway capacity under cutover load
Cutover concentrates traffic. Consumers retry failed calls, token requests spike when applications re-authenticate, and both old and new gateways may carry load during the overlap period. A gateway sized for steady state can slow down or drop requests at this point. Prevention: load-test the WSO2 gateway and key manager at peak plus retry volume, confirm the sizing with WSO2 or your platform team, and define a rollback path that returns traffic to Azure API Management within a set window.
Questions buyers ask before moving from Azure API Management to WSO2
How much effort and cost does moving from Azure API Management to WSO2 involve?
The effort depends mainly on how many APIs, policies, products and consumers you have, and on how much custom policy logic must be re-implemented. Cost has two layers. One-time costs cover discovery, mapping policies to WSO2 mediation and traffic management, importing definitions, testing, cutover and documentation. Recurring costs cover the infrastructure for the gateway, control plane and developer portal, the people who operate them, and any WSO2 commercial subscription. Ask for a quote built from a written scope that lists API count, policy types, environments, identity integration and the number of developer accounts. No figure in this answer is a substitute for that quote.
How long does a migration to WSO2 API Manager take?
Duration is set by the scope and by how much of your program can be moved in waves. The main drivers are the number of APIs and products, how many policies use custom XML or named values, the depth of Microsoft Entra ID or other identity integration, the number of consumers that must change endpoints or credentials, and the change windows your organization allows. Plan separate phases for discovery, a pilot API, bulk import, consumer cutover and decommissioning Azure. Ask any provider to state its phases and durations in the written scope, and ask what you must provide for each phase.
What does the migration require from our own team?
Expect to supply several roles: an API owner for each product who can confirm behavior and approve cutover, an identity engineer for Entra ID or other token issuers, a platform or Kubernetes engineer for hosting the gateway and control plane, a security reviewer for certificates, secrets and access policies, and a consumer liaison who can contact internal and partner teams. Your team also owns the inventory of consumers and the test cases that prove each API behaves the same after the move. Confirm these roles and their time commitments before the work starts.
Can our own engineers migrate from Azure API Management to WSO2 without a partner?
Yes, a capable internal team can do the work, provided it has time, the right skills and clear acceptance criteria. Your team needs experience with OpenAPI, gateway policies, Java-based product deployment (the repository notes JDK 21 for building WSO2 API Manager 4.7.0), Kubernetes or on-premises hosting, and identity protocols. Many teams do the discovery and data export internally and bring in outside help for the policy mapping, hardening and cutover. A fixed-scope partner engagement can cover any part of this list. Decide the split in writing so nothing is left unowned.
Do we need a paid WSO2 subscription to run API Manager?
WSO2 API Manager is licensed under Apache-2.0, so the open-source distribution can be used and modified under that license. WSO2 separately sells commercial subscriptions that provide expert support, continuous product updates, vulnerability monitoring and access to a licensed distribution for commercial use, according to its repository. Whether you need one depends on your support obligations, how quickly you need security fixes, and your internal capacity to monitor and patch. Have legal and security review the license terms and the subscription options with WSO2 before you commit to a design.
How do we migrate developer accounts, applications and credentials?
Treat credentials as a separate workstream. Export developer accounts, applications and subscriptions from Azure API Management, then decide what can be moved and what must be re-issued. Passwords and secrets generally cannot be exported in usable form, so consumers usually need to sign in again or receive new keys. Plan a window where old and new keys both work, communicate it to each consumer, and set a retirement date. Re-create subscription tiers as WSO2 throttling policies and API products, then test that each consumer's quota and access match what it had before. Confirm the exact export options with your provider and with WSO2 documentation.
What should we ask for in a quote for this migration?
Ask for a written scope with these inputs stated: the list of APIs, products and policies in scope, the number of consumers and developer accounts, the identity providers involved, the target deployment (on-premises, Kubernetes or a managed cloud service), environments to build, and the test and acceptance criteria. Also ask which deliverables are included, such as the policy mapping document, migration runbook, cutover plan and documentation, and what is excluded, such as application code changes in consumers. Request separate lines for one-time work and recurring support, and ask what WSO2 subscription costs, if any, are assumed and who pays for them.
Which Azure API Management features will need extra design work in WSO2?
Expect extra design work wherever your Azure setup uses custom policy XML, named values tied to Key Vault, or behaviors that depend on Azure-specific networking and identity. WSO2 API Manager provides a gateway for routing, mediation and security, a traffic manager for throttling, and Publisher and Developer Portal interfaces, and it can be extended with custom authenticators, policies and workflows. Map each Azure policy to a WSO2 equivalent or a custom extension, and record any gap as a decision your business owns. Confirm each mapping through testing rather than assuming it works.
How DeployOpen scopes and runs an API Management migration
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including the move from Azure API Management to WSO2 API Manager. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Inventory every API, product, subscription tier, policy and developer account exported from your Azure API Management instance.
- Define which APIs move first, which stay on Azure during cutover, and which consumers need advance notice.
- Agree in writing the deliverables, timelines and any ongoing support retainer before the migration work begins.
How we build
- Import OpenAPI definitions into WSO2 API Manager and re-create products as API products with matching subscription tiers.
- Map Azure policies such as rate limits, JWT validation and transformations to WSO2 gateway policies and test each one.
- Configure the Developer Portal, migrate developer accounts and applications, and test credential reissue before any DNS change.
How we hand over
- Document the target architecture, configuration, runbooks and the mapping from every Azure policy to its WSO2 equivalent.
- Provide a cutover plan that lists DNS changes, credential reissue steps, consumer notices and rollback steps for each API.
- Walk your platform and API teams through operating the gateway, traffic manager and portal, and the upgrade path for WSO2 API Manager releases.
How we support
- Support is agreed as a fixed-scope engagement, with ongoing support, upgrades and continuous testing available as a retainer.
- Hardening and backup of the WSO2 deployment can be included in scope, with the controls and evidence prepared for your compliance assessments.
- DeployOpen prepares systems and evidence for compliance assessments, while independent auditors and certification bodies issue any reports.
