The Azure API Management developer portal, and the CAPTCHA deadline in front of it

Two ways to run the same portal

The repository is managed by the Microsoft Azure API Management team and contains the source code of the developer portal, with the official Azure documentation carrying the instructions.

The description at the repository level is one line: developer portal provided by the Azure API Management service.

That line hides the most important structural fact about the project, which is that the portal comes in two forms. There is the managed developer portal, which the Azure API Management service runs for you, and there is the self-hosted developer portal, which is this codebase running in your own environment.

Everything else in the repository follows from that distinction. The release guidance says the master branch is used for daily development purposes and may contain an unstable version of the software, and that releases are recommended for setting up your portal. If you are running the portal yourself, you take a release artefact, and the master branch is where the work happens.

That guidance is easy to overlook and it is the difference between a stable deployment and a broken one, because a self-hosted portal is a web application you are responsible for running and updating. There is no managed service to roll a bad build forward for you.

The recent releases show a steady cadence: 2.35.0 on 2026-10-13, 2.34.0 on 2025-10-22 and 2.33.0 on 2025-04-29. The version line moves in minor increments over a year-scale rhythm, which is a sensible pace for a product that is deployed by many organisations and that has to keep working.

The project is TypeScript, MIT licensed, with the default branch master and the last push on 2026-10-13, the same day as the latest release.

A dated change that will break sign-up if you ignore it

The important notice in the documentation is about the legacy HIP CAPTCHA service being retired, with API Management switching to its managed proof-of-work solution.

The requirement is specific and dated. If you self-host the developer portal, update to release 2.35.0 or later by November 20, 2026, before HIP is disabled for your API Management service.

And then the consequence of not doing it, which is the part worth internalising. Release 2.34.0 and earlier do not support the powEnabled setting, and without this update, CAPTCHA-protected sign-up, password reset and password change flows may stop working.

So the failure mode is not cosmetic. When HIP is disabled on the service side, a portal running an older release will find that the three flows that depend on CAPTCHA stop working, and those are exactly the flows a user-facing portal needs in order for people to register and manage their accounts.

The mechanism behind the change is worth understanding as well. The replacement is a proof-of-work CAPTCHA, which is a different kind of challenge from the image-based one HIP provided: the client has to do a small amount of computational work to produce a token, rather than a person choosing objects in a picture. That kind of challenge is a good fit for an API that a browser calls directly, which is exactly what the developer portal's sign-up forms are.

The important operational point is that this is a coordinated change across two systems. The service side has a date on which it switches behaviour, and the portal side has a version in which it can cope with the new behaviour. If either side moves without the other, the flows break.

For anyone running a self-hosted portal, the sensible response is to treat the November 20 date as a hard deadline and to check the version you are running before you start planning the upgrade, rather than after the service side disables HIP for your resource.

Where to report problems, and where not to

The interactions section is the most practically useful part of the documentation, because it tells you which channel will actually get you an answer.

For the managed developer portal, bugs go to Azure Support plus Troubleshooting in the Azure portal, and feature requests go on the Azure Feedback Forum.

For the self-hosted developer portal, bugs go in the repository's Issues section, and feature requests go under the Feature requests discussion section.

Then there is the support boundary, and it is spelled out in detail. Microsoft Azure Support assistance is limited to managed portals and only the initial setup of self-hosted portals. Best effort support is provided for problems caused by environmental factors, such as hosting platform, development environment and network configuration. Other self-hosted portal assistance requests, for example a problem with custom widgets, should be submitted on Stack Overflow with the azure-api-management tag.

And the last clause is the one that saves people the trouble of filing in the wrong place: they do not provide support through GitHub Issues.

That looks contradictory next to the instruction to report self-hosted bugs in the repository's Issues section, and it is worth reading carefully. The distinction is between a defect in the product and a problem with your deployment. A bug in the portal code is a GitHub issue. A portal that will not start because of your hosting configuration is an Azure Support case, and a question about how to build a custom widget is a Stack Overflow question.

The split makes sense as a workload decision. Azure Support is staffed for a managed product with a defined support contract, and extending it to every self-hosted configuration problem would not scale. Routing the work to where it can be answered is what the guidance is doing.

The documentation also says that community contributions are welcome and points at a CONTRIBUTIONS.md file, and there is a SECURITY.md for security reports.

Eight webpack configurations, because the portal is several applications

The repository layout and the script list together explain what this codebase actually is, and the answer is that it is several applications in one repository.

There are eight webpack configuration files at the root: webpack.build.js, webpack.develop.js, webpack.designer.js, webpack.publisher.js, webpack.runtime.js, webpack.function.js, webpack.staticData.js and webpack.mockStaticData.js. Each one produces a different output, and the scripts name them.

The develop script runs webpack-dev-server with the develop configuration and opens a browser, so that is the local development loop. The build script produces the main bundle. Then there are the separate builds: build-designer, build-publisher, build-runtime and build-function, each with its own target.

The designer and the publisher are the two halves of the authoring story. The designer is the visual editor where a portal is put together, and the publisher is the process that takes the designed content and produces the actual portal, which is why publish runs the publisher build and then the index.js it produces, and then serves the website:

        "publish": "webpack --config webpack.publisher.js && node dist/publisher/index.js && npm run serve-website",

The static data scripts are the same idea for a portal with no live API behind it. build-static-data produces the data and runs the publisher against it, and build-mock-static-data does the same with mock data, and serve-static-website chains the two together. That pair is how you preview or demo a portal without standing up an API Management instance.

The function build is for the Azure Functions deployment path, and the deploy script ties it together:

        "deploy-function": "npm run build-function && cd dist/function && func azure functionapp publish < function app name >",

It builds the function bundle, changes into the dist/function directory and publishes with the Azure Functions command line tool. So there is a serverless deployment option alongside the static one.

The runtime build is the third target and is the part that runs inside the portal itself, distinct from the site that serves it.

The tests are run with mocha, loading a mocha.js setup file and running the spec files under src, with an --exit flag:

        "test": "node node_modules/mocha/bin/_mocha -r mocha.js --exit src/**/*.spec.ts",

There is also a playwright.config.ts, so the end-to-end layer is Playwright, and eslint with an eslintrc.cjs configuration for linting, plus an editorconfig, a tsconfig and a postcss config. The .pipeline/ directory holds the deployment pipeline definitions and .vscode/ holds the editor settings.

The Node requirement is pinned in the package file as greater than 18 and less than 23, which is a wide window that still excludes both ends of what is current.

The rest of the tree tells you what the portal is made of

The remaining top-level directories map onto the parts of a developer portal, and reading them is a reasonable way to understand the scope.

There is auth/, which is the sign-in and account handling, which is also where the CAPTCHA flows live that the deprecation notice is about. There is community/, which is the support and discussion features that a developer portal offers alongside the API catalogue. There is templates/, which are the portal page templates, and scaffolds/, which are the starting points for generating new content in the designer. There is src/ for the application code, tests/ for the test suites, and js/ for additional scripts.

There are also the environment and tooling files that a portal deployment needs. environmentConstants.js sits at the root, which is where the endpoints and service configuration live, and the readme/ directory holds the portal image and related files.

The examples directory has two subdirectories, publisher/ and widgets/, and the widget one is the most interesting for anyone extending the portal. The support guidance mentions custom widgets explicitly as a category of problem that should go to Stack Overflow rather than to GitHub Issues, and the example directory shows that widgets are a supported extension point with a published example.

The scripts.v3/ directory is another interesting name, suggesting a versioned generation of the build scripts alongside the current ones, which is a common pattern in a codebase that has been running for years and has needed to change its tooling without breaking existing deployments.

The scripts/ directory is separate from scripts.v3/ and holds the operational scripts, and the package.json pins the package as apim-developer-portal with version 2.33.0 and Microsoft as the author.

That version number is worth noticing against the release list. The newest tagged release is 2.35.0 while the package file on master says 2.33.0, which is a reminder of what the release guidance says: master is for daily development and may not correspond to a released version. The version in the package file on any given branch is not necessarily the version you would get from the releases page.

Where this fits against the managed portal

The decision for anyone looking at this repository is really a decision about whether to run the portal at all.

If you use Azure API Management and let Microsoft host the developer portal, then this repository is interesting to you for a different reason. You can read how it is put together, you can file a feature request on the Azure Feedback Forum, and you can look at the source of the portal your own users are looking at. But you are not going to run it.

If you self-host, the trade is different. The reasons to self-host are usually branding and control: you want the portal to look and behave like your own developer programme rather than the generic Microsoft one, you want to add widgets, or you need the portal to live inside your own network boundary. The reasons to be cautious are also clear. You are running a web application with authentication, account management and a CAPTCHA integration, and you are the one who applies the security patches.

That is where the dated CAPTCHA notice becomes the concrete example. A self-hosted portal is coupled to the behaviour of the Azure API Management service it talks to, and when the service changes its CAPTCHA implementation on a fixed date, your deployment has to move in step. That is a genuine operational dependency and it is the kind of thing to plan for rather than discover.

The alternative to self-hosting is not nothing, it is the managed portal plus whatever customisation Microsoft offers, and for many teams that is the right answer precisely because someone else owns the update burden.

The other option worth naming is building your own portal against the service, which gives you complete freedom and complete ownership. The developer portal in this repository is a good reference for that, because it shows one way to consume the service, but it is a large codebase to maintain.

So the practical framing: adopt this repository if the branding or control reasons are strong enough to take on the update responsibility, and check the release notes against your current version before you decide, because that is where the obligations are described.

Editorial conclusion

Adopt this repository if you run a self-hosted API Management developer portal, since the CAPTCHA change is mandatory by a fixed date and the codebase is what you maintain. Skip it if you use the managed portal, since Microsoft hosts and updates that for you. Verify first which release you are on, since 2.34.0 and earlier do not support the powEnabled setting, that you read the self-hosting documentation before changing anything, and where to raise problems, since self-hosted issues are not handled through GitHub Issues and the Stack Overflow tag is the right channel for custom widget problems.

Frequently asked questions

Official sources

1. Azure/api-management-developer-portal on GitHub
2. Issues
3. License: MIT
4. README
5. Releases