Azure API Management Developer Portal: Limits, Common Problems and When to Go Custom (2026)

TL;DR

The Azure API Management (APIM) developer portal is a built-in website where developers find your APIs, read docs, test calls and get subscription keys. It comes with every tier except Consumption, at no separate charge.

It works well for a simple public or partner catalog. The limits show up as you grow: v2 tiers drop custom widgets and reports, deep changes mean self-hosting an open-source codebase, and in 2026 the most common complaints were notification emails not arriving and sign-ups failing.

Stay with the built-in portal if it covers your sign-up and branding needs. Consider a custom portal when developer onboarding is a revenue or partner channel you can't afford to break.

The developer portal is often the first thing an outside developer sees of your API program. It's set up at launch, checked once, and then left alone, because the gateway behind it keeps working.

The trouble is that a portal can fail quietly. A sign-up that never gets its confirmation email doesn't raise an error on your side. The developer just leaves.

So, two quick counts.

First, how many developers signed up to your portal last quarter? Your team probably has a rough number.

Now open the Users list in your APIM instance and filter by state. Count the accounts still marked Pending, the people who signed up and never confirmed.

Most teams have never looked at the second number.

What is the Azure API Management developer portal?

The Azure API Management developer portal is an automatically generated website where developers discover your APIs, read reference docs, try calls and request access. Microsoft hosts it for you, and you design it in a drag-and-drop editor. It's part of every APIM tier except Consumption.

Definition: The Azure APIM developer portal is defined as a managed, customizable website, generated from the APIs and products you publish in API Management, that handles developer sign-up, documentation, testing and subscription keys.

Out of the box, it gives you:

• An API catalog and reference docs: Built from the APIs and products you publish. Unpublished APIs don't appear.
• A "Try it" console: Developers call your APIs from the docs page, with no auth, a subscription key or OAuth 2.0. It needs a CORS policy on your APIs.
• Products and subscriptions: Developers subscribe to products and get keys. Groups control who sees which products.
• Sign-up and sign-in: Username and password (with CAPTCHA), Microsoft Entra ID, delegation to your own site, and Azure AD B2C as legacy support.
• Usage reports for each developer: Signed-in users see their own calls, data transfer and response times for up to 90 days.
• A visual editor: Pages, layouts and styles, with save, publish and rollback.

One change to know about: portals created after June 2025 use a redesigned interface built with Fluent UI and React. Older portals can preview it, and resetting a portal switches it to the new design for good, according to Microsoft's developer portal overview.

What does the developer portal include on each tier?

The portal is in every tier except Consumption, but the v2 tiers leave out several customization features. If you're choosing between classic and v2 tiers, check this table first. The portal itself has no separate line on Azure's price list.

Sources: Microsoft's v2 tiers overview (September 2026), feature comparison (June 2026), WordPress plugin and Entra ID pages (March 2026), and Azure service limits (August 2026).

Read the v2 column closely. Many teams move to v2 for faster setup and lower prices, then find their custom widgets won't come with them. Our Azure API Management pricing guide covers the tier prices.

What are the limits of the default Azure APIM developer portal?

The built-in portal is quick to launch but hard to bend. Its limits are less about how it looks and more about what you can change, where it runs and what happens when something breaks.

• Deep changes mean self-hosting: Changing how sign-up, onboarding or navigation work beyond the editor means running the open-source portal yourself. Microsoft says to do that "only when you need to modify the core" of the codebase.
• Self-hosted means you own the upkeep: Azure Support only helps with the basic setup of a self-hosted portal. You host it, patch it and merge updates yourself. Its latest GitHub release, 2.34.0, shipped in October 2025, with no release so far in 2026.
• Custom code isn't supported: Microsoft says it doesn't support the HTML you add in the custom HTML widget, and custom widget code is served from an endpoint that doesn't require authentication.
• v2 tiers remove options: No custom widgets, no reports and no WordPress plugin, plus caps on pages and media files.
• Email depends on Microsoft's relay: APIM sends notification emails itself. There's no documented way to use your own mail server, and you can't sign mail with your own DKIM key.
• Sign-in choices are narrowing: Azure AD B2C closed to new customers on 1 May 2025, and there's no native option for a standalone Entra External ID tenant, as of October 2026.
• One gateway, one catalog: The portal only shows APIs from that APIM instance. APIs on other gateways need a separate portal.

What are the most common Azure APIM developer portal problems, and how do you fix them?

In 2026, most developer portal problems were about email and sign-up, not design. We reviewed 47 Microsoft Q&A threads about the developer portal, 37 of them from 2026. Of those, 14 were about notification emails and 8 were about sign-up failures. Many accepted answers point to a support ticket or a fix on Microsoft's side, not a setting you can change.

Why is the APIM developer portal not sending emails?

Check your Azure subscription type first. Microsoft's notification docs, updated in July 2026, list four restrictions:

If none apply, it may be on Microsoft's side. In mid-2026, a Microsoft moderator described an overloaded email pipeline across regions, eased by throttling. Some customers got email working only after Microsoft enabled it for their subscription through a support case.

What to do:

1. Confirm your subscription type and the instance's age.
2. Check the Notifications and E-mail settings pages, and the product's "Require subscription approval" setting.
3. Add Microsoft's SPF record if you use a custom sender address.
4. Open a support case if mail still doesn't arrive.
5. For critical onboarding, use delegation so your own site sends the emails.

How do you fix "User registration is not supported" in the developer portal?

It's a known platform issue, not a misconfiguration. Since May 2026, users have reported a 400 error with this message when creating users, through the portal, the Azure portal or the API. Microsoft moderators called it a known APIM issue.

• Workaround Microsoft suggested: Under Identities settings, turn off "Redirect anonymous users to sign-in page". This opens the portal to anonymous visitors, so weigh that first.
• Status: A fix was reported as deployed in late August 2026, but users still reported the error in September. If you hit it, open a support case.

A related July 2026 issue created sign-ups stuck as Pending, with no confirmation email. Microsoft confirmed a fix on 21 July 2026, but it's worth checking your Pending users either way.

Why does Entra ID or Entra External ID sign-in fail?

Usually because of what the portal supports, not your setup.

• Entra External ID (CIAM) isn't supported natively: The portal's identity providers expect a workforce tenant or Azure AD B2C. The workarounds are delegation, or inviting external users into a workforce tenant.
• B2C is closed to new customers as of 1 May 2025. Existing B2C setups still work.
• ADAL stopped working on 30 September 2025: Identity providers must use MSAL. If yours keeps saving as ADAL, set the client library to "MSAL-2" through the API and republish.
• The admin account can't sign in with Entra ID if its email matches the built-in administrator account. Change the built-in admin's email.

Why won't custom widgets deploy or edit?

• On v2 tiers, they don't exist: Custom HTML and custom widgets are classic-tier features only.
• Deploy errors such as CredentialUnavailableError often come from a blocked local port. Removing a deployed widget needs Microsoft Support.
• Can't re-edit a custom HTML widget? Select it from the outline panel instead of the page, because its iframe blocks clicks.

How do you fix Content Security Policy (CSP) warnings?

CSP is off by default, so security scans flag it. Turn it on under Developer portal → Portal settings → Content security policy. Don't start with a default-only policy, because it blocks sign-in redirects and Try-it calls. Add explicit sources for scripts, styles, connections, images and frames, and test before you enforce.

How do you control or fix the Try-it console?

• Hide it from anonymous users: Remove the Guests group from the product, or change access on the console section.
• Use OAuth in Try-it: SAet up an OAuth 2.0 or OpenID Connect server for the console. Portal sign-in and API authorization are separate.
• Empty request bodies were reported in March 2026, with no fix yet.

Other issues teams hit

Pick the built-in portal's fixes if these issues are occasional for you. Look at alternatives if sign-up and email failures are costing you developers, because many of the fixes sit with Microsoft, not you.

How do you customize the Azure APIM developer portal?

You have three routes, and each one trades control for effort. Start with the visual editor, move to widgets for small additions, and self-host only when you must change how the portal works.

Delegation is a fourth option for sign-up only. It hands sign-up, sign-in and subscriptions to your own website, while the portal keeps the docs. It works on classic and v2 tiers, and it's the usual workaround for email and identity problems.

For a wider look at what a strong portal includes, see our guide to the best API developer portals.

When should you replace or front the built-in portal?

Replace or front the built-in portal when developer onboarding becomes a business channel, not just documentation. If partners sign revenue contracts through your portal, a missed confirmation email is a lost deal, not a support ticket.

Stay with the built-in APIM developer portal if:
‍
• All your APIs run on one APIM instance.
• Your developers are mostly internal, or signed up by hand.
• The visual editor covers your branding.
• You're on a classic tier, or don't need custom widgets.

Consider a custom portal if:
• Sign-up, invite or subscription emails have failed for your developers.
• You need Entra External ID or another customer identity provider.
• You're on a v2 tier and need custom components.
• Your APIs sit on more than one gateway, such as APIM plus Apigee, Kong or AWS.
• You want to charge for APIs, with plans and billing in the portal.

Postman's 2025 State of the API report found that 31% of organizations run more than one API gateway. For those teams, a portal tied to one APIM instance only shows part of the catalog.

How do you move to a custom developer portal without losing access?

Keep Azure API Management as the gateway and change only the front door. Developers keep their keys and endpoints. Only the website they sign up on changes.

1. List what developers use today: Export your APIs, products, subscriptions and users from APIM.
2. Connect the new portal to APIM: Sync APIs and products into it, so docs stay generated from the same specs.
3. Keep existing credentials working: Map current subscription keys, or keep Entra ID tokens, so no developer has to re-register.
4. Move sign-up and approvals: Route new sign-ups and subscription approvals through the new portal, or through APIM's delegation.
5. Redirect the old portal: Point your portal custom domain at the new site, and redirect old doc URLs.
6. Tell developers once: Send one notice with the new address, and watch sign-up completion for the first month.

Watch the Pending count. It's the quickest sign that the new sign-up flow works.

How does DigitalAPI's developer portal work with Azure API Management?

You can keep Azure API Management as your gateway and run a better portal on top of it. APIM stays in place, and traffic keeps flowing through it. DigitalAPI's portal connects to APIM, pulls in your APIs, and runs sign-up, subscriptions and docs in one branded place.

Teams using DigitalAPI cut developer time-to-first-call by putting discovery, sign-up, keys and testing in one self-serve flow. What that looks like:

• One catalog across gateways: Azure APIM APIs sit next to APIs from Apigee, Kong, AWS and others, with search and role-based visibility.
• Self-serve onboarding: Developers sign up, pick a plan and get credentials, while API owners approve where needed.
• Products, plans and billing: Package APIs into plans, with built-in billing and Stripe support.
• Governance scores: Each API gets a score for security, style and documentation before it's published.
• Ready for AI agents: Generate MCP servers from your OpenAPI specs, and let developers ask API GPT which API fits their use case.
• Your deployment choice: SaaS, private cloud or on-premises.

Read how it works in practice in our guide to cataloging Azure APIs the right way, or see the API developer portal product page.

Want developers to get from sign-up to first call without the email lottery? Get an assessment of your API landscape → Talk to our experts

FAQ

What is the Azure API Management developer portal?

The Azure API Management developer portal is a built-in, Microsoft-hosted website where developers discover your APIs, read reference docs, test calls in a "Try it" console and get subscription keys. It's generated from the APIs and products you publish, and you design it with a drag-and-drop editor.

Is the developer portal included in Azure API Management pricing?

Yes, on every tier except Consumption. Azure's price list shows the developer portal as included in the Developer, Basic, Standard, Premium and v2 tiers, with no separate charge listed. The Consumption tier has no developer portal.

Does the developer portal work on the v2 tiers?

Yes, but with fewer features. Basic v2, Standard v2 and Premium v2 include the managed portal, but not custom HTML widgets, custom widgets, usage reports or the WordPress plugin. They also cap pages at 30 or 50 and media files at 15, as of October 2026.

Why is my Azure APIM developer portal not sending emails?

The most common reason in 2026 is the subscription type. Microsoft has suspended email for Pay-As-You-Go and MSDN subscriptions until further notice, doesn't support it on Free Trial subscriptions, and pauses it for three days after an instance is created. If none apply, open a support case.

What does "User registration is not supported" mean in APIM?

It's a known Azure API Management platform issue reported since May 2026, not a configuration mistake. Microsoft suggested turning off "Redirect anonymous users to sign-in page" as a workaround, which opens the portal to anonymous visitors. If the error persists, open a support case.

Can I use Entra External ID with the APIM developer portal?

Not natively, as of October 2026. The portal's identity providers support Microsoft Entra ID workforce tenants and Azure AD B2C, which closed to new customers on 1 May 2025. The workarounds are delegation to your own sign-in site, or inviting external users into a workforce tenant.

Can I self-host the Azure APIM developer portal?

Yes. Microsoft publishes the portal's code as open source under the MIT license. Self-hosting lets you change anything, but Azure Support only covers basic setup, and you're responsible for hosting, security patches and merging updates. Microsoft recommends it only when you need to change the core codebase.

What is the best alternative to the Azure APIM developer portal?

It depends on your needs. Teams with one APIM instance often stay with the built-in portal and use delegation for sign-up. Teams with APIs on several gateways, or who sell APIs, usually choose a third-party developer portal that connects to APIM and adds plans, billing and a multi-gateway catalog.

Final word

• The built-in portal is a fast, included way to publish APIs from one APIM instance.
• Its limits show up on v2 tiers, in deep customization and in sign-up and email reliability.
• A custom portal makes sense when onboarding is a partner or revenue channel, or your APIs span gateways.

Start with the count at the top: open your Users list and check how many developers are still Pending. That number tells you whether your portal is quietly losing people.

Want a clear view of your developer onboarding and API landscape? Get an assessment from DigitalAPI → Talk to our experts