Replacing the Azure API Management developer portal with self-hosted open source
If your renewal, a data residency rule or a wish to stop depending on the Azure-hosted portal is pushing you to move, the portal is the part of Azure API Management you can replace most cleanly. Gravitee APIM and WSO2 API Manager both ship external developer portals with sign-up, documentation and subscriptions, while Backstage fits best as an internal API catalog for APIs that only your own engineers consume. The portal is one module of the platform, not the whole platform, so your gateway and identity provider can often stay where they are while the portal moves.
Both Gravitee and WSO2 API Manager are licensed under Apache-2.0, and their repositories include a gateway, a management backend, a publisher or console for administrators and a developer portal. Gravitee's documentation, however, states that its Enterprise Edition requires a license, and several portal-adjacent features sit behind it. Its Enterprise Edition list includes audit trails of API consumption and activity, Dynamic Client Registration, and an enterprise policy pack. Before you commit, confirm with Gravitee which of your required portal and access features are in the Community Edition and which need a license, and ask WSO2 which parts of its commercial subscription you need for support and continuous updates. Backstage is also Apache-2.0 with no paid edition from the project itself, but its catalog and TechDocs are built for internal use rather than sign-up by external partners.
The practical decision is which audience you serve. For external developers who need self-service keys, plans and usage visibility, evaluate Gravitee or WSO2 and test the portal with a few representative APIs. For internal teams, Backstage can index your APIs from the catalog and link to their documentation, and its authentication guidance recommends sign-in resolvers that map every provider to one identity and no guest access in production. Plan how existing Azure developer accounts, subscription keys and API documentation are exported and re-created, and confirm with each vendor how credentials are re-issued so consumers are not cut off during cutover.
Which portal capabilities map to which open-source option
This table maps the main capabilities of the Azure API Management developer portal to the open-source options that can replace them. Read each row against your consumer groups, since partner and public audiences need sign-up, keys and analytics that internal catalogs often do not provide. Backstage covers internal APIs and documentation well, but it does not replace an external developer portal.
| Capability | Gravitee Portal UI | WSO2 Developer Portal | Backstage API catalog and TechDocs |
|---|---|---|---|
| API documentation | Portal UI provides a catalog of APIs with documentation, per the repository README. | Developer Portal publishes API documentation from the Publisher; confirm OpenAPI, GraphQL and AsyncAPI rendering. | Software Catalog entries with TechDocs documentation written in Markdown and built from the repository. |
| Sign-up and approval | Confirm self-service sign-up and approval workflows in the Portal UI for your edition. | Confirm self-service registration and admin approval steps in your release and licensed distribution. | Not a consumer sign-up flow. Sign-in is through configured identity providers for staff. |
| Subscriptions and keys | Subscriptions and keys are managed through API Management; confirm self-service key issuance in the portal. | Subscription tiers and application keys are part of the portal model; confirm rotation and revocation steps. | No API subscriptions or keys. Access control for internal APIs stays with the gateway or service owner. |
| API testing console | Confirm whether the Portal UI offers a try-it console for each API. | Confirm whether the Developer Portal offers try-out for each API and how it handles credentials. | No built-in testing console. Link to external API clients from catalog entries if needed. |
| Customizable branding | Confirm theme, logo and layout options in the Portal UI for your edition. | Confirm theme and branding customization options in the Developer Portal documentation. | Branding is set through the Backstage app and theme configuration, which needs frontend development. |
| Consumer analytics | Consumer-facing analytics need confirmation. Audit trails of API consumption are an Enterprise Edition feature. | Confirm which usage and analytics views consumers see; traffic management features are in the gateway. | No consumer analytics out of the box. Usage data depends on plugins and your own telemetry stack. |
| Internal service catalog | Catalog of published APIs fits internal discovery, but service ownership is not its focus. | Publisher and Developer Portal fit API programs; confirm fit for internal-only services without consumers. | Software Catalog tracks services, owners, dependencies and docs, which is its core design purpose. |
Gravitee, WSO2 API Manager or Backstage: which portal fits
Each card covers a different way to publish API documentation to developers: a full lifecycle suite with a built-in portal, an enterprise suite with a Developer Portal and Publisher, or a catalog framework for internal APIs. Choose based on who the consumers are, which deployment your team can run, and who will keep the platform upgraded.
Gravitee Portal UI for partner APIs
Gravitee's Portal UI is the catalog of APIs with documentation, and it sits beside the Console UI that administrators use. It fits an external partner program where you want one product for the full lifecycle, from gateway policies to the documentation partners read. Deploy with the Helm chart on Kubernetes (AKS, GKE, EKS and OpenShift are listed) or with Docker Compose and MongoDB for smaller installs. Before you commit, check the Enterprise Edition feature list, because data masking, the Alert Engine and Dynamic Client Registration need a license.
WSO2 Developer Portal for enterprise programs
WSO2 API Manager pairs a Developer Portal with a Publisher, a control plane, a gateway and a traffic manager, so one product covers publishing, consumer onboarding and throttling. It suits enterprises with many internal and partner APIs and a mix of REST, GraphQL and AsyncAPI definitions. You can run it on premises from extracted packages, as a managed cloud service, or on Kubernetes through the separate WSO2 API Platform for Kubernetes. Building from source needs JDK 21, and commercial subscriptions add expert support, continuous updates and vulnerability monitoring, so price those alongside the license for commercial use.
Backstage for internal API catalogs
Backstage works as a software catalog and documentation portal for internal APIs, listing owners, components and TechDocs. Sign-up, subscriptions and key issuance have to come from a gateway or another system beside it. Backstage is Apache-2.0 licensed with no paid edition from the project, and the CNCF accepted it on September 8, 2020, moving it to Incubating on March 15, 2022. Route sign-in through one identity provider with a resolver that maps every provider to the same identity, and disable guest access in production.
Planning Backstage upgrades
Treat Backstage upgrades as recurring work. The main release line ships monthly, on the Tuesday before the third Wednesday, and the next release line ships weekly on Tuesdays. Backstage supports two adjacent even-numbered Node.js releases, which were Node.js 22 and 24 as of 1.46.0, so Node upgrades often arrive alongside framework upgrades. The versioning policy says high and critical vulnerabilities are backported to releases from the last 6 months where feasible, so falling behind that window leaves you without guaranteed fixes. Name an owner for the monthly cycle before launch.
Running the new portal beside Azure-hosted gateways and Entra ID
Some teams keep their Azure API Management gateways for traffic that already runs there and move only the developer-facing portal to a self-hosted product. In this split, the portal must still reach the APIs and the credentials it issues must still be accepted by the gateways that enforce them. Confirm early how the portal's subscription keys and tokens map to what the Azure gateway validates, because a mismatch shows up as failed calls rather than as a clear error.
- Key mapping: Confirm whether subscription keys issued by the new portal are accepted by the Azure gateway, or whether consumers must move to token-based access.
- Routing ownership: Decide which team owns the API definitions the portal publishes when the runtime stays in Azure.
- Network path: Check that the self-hosted portal can reach the Azure-hosted endpoints it documents and tests against.
- Duplicate records: Avoid two sources of truth for plans and subscriptions during the transition.
- Recurring cost: Azure tiers continue to bill for the gateway while the portal adds hosting and operating effort.
Before committing, confirm the exact key and token behavior with the Azure and portal vendors in writing, and test it with one API.
Moving the gateway and the portal together removes the split-brain risk of two management planes. Gravitee and WSO2 API Manager both bundle a gateway, a management backend and a developer portal, so consumers sign in and subscribe to the same system that enforces their plans. The work moves into a cutover plan, with DNS changes, credential reissue and a period when old and new endpoints both run.
- Single control plane: Gravitee's gateway, management API backend, Console UI and Portal UI, or WSO2's gateway, Publisher, Developer Portal and traffic manager, run as one product.
- Deployment choice: Gravitee documents Helm charts for AKS, EKS, GKE and OpenShift, and WSO2 supports Kubernetes through its separate platform.
- Edition check: Confirm which portal and analytics features need Gravitee's Enterprise license before you design around them.
- Credential reissue: Plan how existing developers receive new keys and how old ones are retired.
- Staged cutover: Move one API product at a time and keep the Azure endpoint available until consumers confirm.
Ask each vendor which portal features are in its community distribution and which require a commercial license.
For internal-only APIs, a Backstage software catalog can list documentation and ownership without a full API gateway product in front of every service. Backstage is Apache-2.0 licensed and has no paid edition from the project itself, so the cost sits in hosting, plugin work and the team that maintains it. Its authentication model is the part that needs the most design, since sign-in decides who can see internal API documentation.
- Identity providers: Backstage ships 19 built-in authentication providers, including Azure, Okta and generic OIDC, so an Entra ID tenant can be federated through the Azure provider or through OIDC.
- One identity: Configure sign-in resolvers so every provider resolves to the same user identity, per the authentication guidance.
- No guest access: Do not offer guest access in production.
- Database and cache: Backstage uses PostgreSQL in production and supports Redis or in-memory caching.
- Node.js support: Backstage 1.46.0 supports Node.js 22 and 24, so confirm the runtime version before deployment.
Confirm the Entra ID app registration, redirect URIs and group mapping with your identity team before rollout.
Identity is the shared concern across all three splits. Azure API Management portal users typically sign in with Microsoft accounts or Entra ID, so the new portal needs a deliberate way to recognize the same people. Federating Entra ID as an OIDC provider in Gravitee, WSO2 or Backstage keeps one directory as the source of truth, while the portal manages API-specific plans and keys on its own.
- Federation: Use Entra ID as an OIDC identity source where the portal supports it, and check the claims the portal reads for roles and groups.
- Account linking: Map each provider to one identity so a developer who signs in two ways does not get two accounts.
- Guest access: Keep anonymous or guest browsing out of production for portals that expose internal APIs.
- Migrating accounts: Decide whether existing Azure developer accounts are matched by email, by Entra object ID or re-invited.
- Access review: Confirm who can approve subscriptions and who can see restricted API documentation.
Review the identity design with your security team and check each vendor's documentation for the exact claim and resolver settings.
Moving developer accounts, subscriptions and keys without breaking consumers
This sequence moves developer accounts, product subscriptions and API credentials from the Azure API Management portal to a self-hosted portal while giving consumers a planned, observable cutover.
Export portal content and the developer list
The API program owner exports the portal content you control, including API documentation pages, product descriptions, groups and the list of registered developers with their sign-up dates, product subscriptions and application names. Confirm the export format and scope with your Azure administrator, because the management tooling you use determines which portal objects you can read. Treat the export as sensitive: it contains personal data about developers. The step is done when you hold a complete inventory that you have counted against the Azure portal, with differences explained.
Decide which accounts migrate and which re-register
Work with the API product owner and the security team to sort developers into groups: active consumers with production traffic, dormant accounts, and internal test users. Migrate the first group by importing identities where the target portal supports it, and ask the vendor or community how it maps sign-in identities, since Gravitee and WSO2 API Manager handle developer identity differently. Ask dormant accounts to re-register, which removes stale data. The output is a signed-off migration register listing each account and its path.
Recreate products and subscription tiers in the new portal
Rebuild each Azure product as the equivalent API product or plan in the new portal, with the same APIs, rate limits and approval rules. Gravitee uses plans on APIs and WSO2 API Manager uses products and subscription tiers, so map each tier explicitly and record any feature that the target does not reproduce. Check every subscription against its new tier before you move any consumer. The step closes when a test developer can subscribe to each product in a staging environment and receive a working credential.
Re-issue or re-map keys for each consumer
Azure subscription keys cannot be read back in clear text from the export, so do not expect to copy them. Either generate new credentials in the target portal for each consumer application, or, if the gateway is configured to accept existing keys, load the key values from your own secure store under a controlled change. Share new credentials only through a channel the consumer owner has verified, and never by email attached to the export. The step is done when every migrated application has a credential that has been tested against the target gateway.
Run both portals in a dual-run window
Keep the Azure portal and gateway serving existing consumers while the new portal accepts sign-ups and the new credentials are tested. Publish a dated notice to each developer group that explains what changes, what they must do, and where they can ask questions. Monitor sign-ins, failed authentications and support tickets on both sides daily during the window, and agree the window length with the consumers and the API owners in writing before it opens. The window closes when no production consumer relies on the old credentials and the open issues are resolved.
Redirect the portal domain and cut over
Point the public portal hostname at the self-hosted portal by changing its DNS record and certificate, and set a short time-to-live on the record ahead of the change so a rollback is quick. Confirm that old portal links redirect to the matching pages in the new portal, and that the sign-in callback URLs for each identity provider are registered. Verify the cutover with synthetic sign-in and subscription tests from outside your network. The step is done when the portal resolves to the new platform and the monitoring dashboards show consumer traffic on the new credentials.
Retire the Azure portal and archive the records
After the cutover is stable, disable developer sign-up and subscriptions in the Azure portal, then remove access for consumers who have not migrated, after notice. Archive the exported inventory, the migration register and the change records under your records retention policy, because auditors often ask how developer access changed. Confirm with your Azure administrator which portal settings and diagnostics you retain. The step is complete when the Azure portal is read-only or removed and the archive has been reviewed by the API owner and the security lead.
What the portal move costs in people, hosting and licensing
The cost of moving the developer portal is mostly people and hosting, not software. The Apache-2.0 base of Gravitee API Management and WSO2 API Manager means the core portal code carries no license fee, but the two products draw the line differently. Gravitee documents that its Enterprise Edition requires a license, and that some portal-adjacent and gateway features sit behind it, so confirm with Gravitee which features your developer experience depends on. WSO2 sells commercial subscriptions for expert support, continuous product updates, vulnerability monitoring and access to the licensed distribution for commercial use. A WSO2 subscription is recurring, and it is the line item that pays for patches you would otherwise track yourself. Backstage carries no paid edition from the project itself, so its cost sits almost entirely in the people and infrastructure around it.
Hosting is a recurring cost that scales with the portal's traffic and data. Gravitee's Docker Compose path uses MongoDB, and Backstage uses PostgreSQL in production, so you will run a database, a portal front end, and the supporting services for search, authentication and caching. Ask each vendor which database versions it supports, how it expects you to size and back up the store, and whether the Helm chart or installer provisions those components or leaves them to you. One-time costs include the migration scripting that moves subscriptions and keys, and the content rewriting needed to turn Azure portal pages, API descriptions and sign-up flows into the new portal's format. Those costs recur only when the portal's content changes often, which is common for active API programs.
The largest recurring cost is the platform team that operates the portal, applies upgrades and answers developers. Backstage's versioning policy describes a monthly main release line and a weekly next line, and it backports high and critical security fixes to releases from the last six months when feasible, so budget time for regular upgrades, not occasional ones. For any quote, ask for: the license scope for each feature you need, the subscription term and what support covers, the hosting components and their sizing assumptions, the hours for scripting and content migration, the upgrade and on-call model, and a clear statement of what is excluded. A fixed-scope written agreement makes these items comparable across vendors and against your current Azure API Management spend.
Questions buyers ask before replacing the Azure developer portal
How much effort and time does moving a developer portal take?
The effort depends mainly on how many APIs, products and developer accounts the portal holds, and on how much custom portal content and branding you have built in Azure. No supplied source gives a duration, so treat any number a vendor or partner quotes as an estimate to test against your own inventory. Start by counting published APIs, subscription products, active developer accounts, and custom pages or CMS content. Each of these adds migration and verification work. Ask any implementation partner for a fixed-scope plan that lists what is moved, what is rebuilt and what is retired, with deliverables agreed in writing before work starts.
Can our internal team replace the portal without outside help?
Yes, many teams do this in-house, especially if they already run Kubernetes and have engineers comfortable with Java-based platforms or Node.js. The main skills are operating the platform's database and gateway, configuring sign-in, building portal content and handling credential migration. Gravitee and WSO2 API Manager both ship as self-hosted products with Helm or Docker-based deployment options, and Backstage is a framework you build and maintain yourself. Outside help is most useful for the first deployment, the identity integration and the cutover plan. Decide early which of these your team can own after go-live.
Can we keep existing developer keys and subscriptions when we move?
Sometimes, but do not assume it. Keys and subscriptions are tied to the platform that issues them, so moving to Gravitee or WSO2 API Manager usually means re-creating applications, subscriptions and plans there and deciding whether consumers receive new credentials. Plan a cutover that keeps old and new keys valid for a defined overlap period, and communicate the dates to each consumer. Confirm with the target vendor's documentation how subscription and key import works in the version you deploy, and test it with a non-production copy of a few real consumer accounts.
Does Backstage replace an external developer portal for our partners?
Not by itself. Backstage is an Apache-2.0 framework for developer portals, with a Software Catalog, Software Templates and TechDocs as core features, and it is built for internal engineering teams and their services. It has no paid edition from the project, so the cost is the engineering effort to build, host and maintain it. Partner-facing needs such as self-service sign-up, API subscriptions, keys and usage views are not what Backstage's catalog is designed around. For internal APIs, Backstage is a strong fit. For external consumers, a gateway-native portal such as the Gravitee or WSO2 portal is usually the closer match, or you can run both.
Which portal features need a Gravitee Enterprise or WSO2 subscription?
Gravitee documents that the Enterprise Edition requires a license and lists features such as data masking, GeoIP filtering, Dynamic Client Registration, the Alert Engine, Redis caching, Cloud Reporter, audit trails and enterprise protocol endpoints. Gravitee's Community Edition is self-hosted and open source under Apache-2.0, so check each portal capability you depend on against the Enterprise Edition page before you design around it. WSO2 API Manager is Apache-2.0 licensed, while WSO2 sells commercial subscriptions for expert support, continuous product updates, vulnerability monitoring and the licensed distribution for commercial use. Ask both vendors to map each feature you use to its license tier in writing.
What does our team need to provide for the migration?
Expect to provide named owners for the API catalog, identity provider, DNS and certificates, and the consumer communication plan. Your platform team needs to supply the target Kubernetes or virtual machine environment, the database service for the chosen platform, and network access between the gateway, the portal and your identity provider. Your API owners need to confirm which APIs and documentation are current, and your security team should approve the sign-in model and how secrets are stored. Ask any partner for a written list of client inputs in the scope, so responsibilities are clear before work starts.
How should we handle sign-in and identity in the new portal?
Connect the new portal to the same identity provider your developers already use, so each person maps to one identity. Backstage ships 19 built-in authentication providers, including Azure, Okta, GitHub and generic OIDC, and its documentation advises configuring sign-in resolvers so every provider resolves to the same identity and not offering guest access in production. Gravitee and WSO2 API Manager also support OpenID Connect integration, but confirm the exact setup in the version you deploy. Test sign-in, role mapping and account linking with a small group before you open the portal to all developers.
What operational work continues after the portal is live?
Once live, the portal needs regular upgrades, backups of its database, monitoring, and a clear process for applying security fixes. Backstage publishes a monthly main release line and a weekly next line, and its policy says high and critical vulnerabilities are backported to releases from the last six months where feasible, so plan upgrades on that cadence. Its supported Node.js versions also change with releases, so check them before each upgrade. Budget for this as recurring engineering time or a support retainer, and agree on the upgrade responsibilities in the handover documentation.
When to keep the Azure portal for a while
Keep the Azure-hosted developer portal running in parallel until consumers have moved, rather than switching it off on the day the new portal goes live. During a staged move, the Azure portal remains the place where existing subscribers sign in, read documentation and manage their keys, while the new portal (Gravitee's Portal UI, the WSO2 Developer Portal or a Backstage catalog for internal APIs) is populated with the same API definitions. Run both for a period that covers at least one full release cycle of each consuming team, and keep the Azure subscription keys valid until traffic on them has stopped. Plan this as a dated checklist, not a single switch.
A second reason to wait is partner dependence. External partners often hard-code the Azure portal's sign-up URL, the branding they recognize, or the email confirmation and password reset flows they were onboarded through. Before cutover, ask the vendor and your own partner managers which of these are in use, and whether the new portal can carry your domain, logo and custom sign-up fields. Confirm with the vendor whether the Community or Enterprise edition of your chosen platform includes the portal features you depend on, since some Gravitee and WSO2 capabilities depend on the edition and licensing you buy. Check the Azure side too: confirm which custom domain and certificate settings are bound to the portal in your own environment, and who in your team owns them.
Set exit criteria before you start. Examples: no active calls from old keys for an agreed window, every partner has confirmed a working login on the new portal, and the Azure developer portal content has been exported and reviewed for anything that was never in the API definitions, such as tutorials or legal terms. Ask your DeployOpen or internal team to confirm, in writing, who approves the switch-off and how credentials are re-issued. Illustrative only: a partner that still embeds the old sign-up link should block the cutover until its integration is updated.
How DeployOpen scopes and delivers a developer portal replacement
DeployOpen plans, implements, customizes, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, including the developer portal and its supporting catalog. We start by agreeing in writing what the replacement portal must cover for your APIs, your developers and your identity setup, then build and hand it over with the evidence your teams need to run it.
How we scope
- Inventory the APIs, owners and existing portal content that the new portal must carry over.
- Confirm which portal (Gravitee, WSO2 API Manager or Backstage) fits your internal and external audiences and identity provider.
- Agree a fixed scope with deliverables and timelines in writing before any work starts.
How we build
- Deploy the chosen portal in your cloud accounts, data center or air-gapped network, with sign-in resolvers mapped to one identity per user.
- Import API documentation, catalog entries and subscription plans, then test sign-up, key issuance and key revocation end to end.
- Test the portal and its authentication and API access paths, and document the results against the agreed scope.
How we hand over
- Provide runbooks for portal upgrades, database backups, plugin or catalog changes and key rotation.
- Document the developer account migration plan, including which accounts move, which need re-invitation and how credentials are re-issued.
- Walk your platform and API teams through operation, so they can run the portal after the engagement ends.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Confirm the release cadence and security patch policy of the chosen platform with its maintainers before setting your upgrade schedule.
- Ask any quote to separate one-time build effort from recurring hosting, support and retainer costs.
