Share via

Unable to publish Developer Portal in Azure API Management (APIM) – fails every time despite successful service deployment and backend testing (Global Admin + Cloud App Admin roles)

Shahzad Muhammad 0 Reputation points
2026-04-10T06:13:48.85+00:00

Hi Microsoft Support Team,

We are facing a persistent issue with our Azure API Management service where we cannot publish the Developer Portal.

Issue Summary:

  • The APIM service deploys successfully.
  • Backend APIs are working correctly (we have tested them and they respond as expected).
  • However, every time we try to publish the Developer Portal (from the Azure portal → API Management service → Developer portal section → Publish button), the operation fails.
  • After each failed publish attempt, the Developer Portal still shows the default “unpublished” page with the following message:

"This is a home page of the Developer portal - an automatically generated, fully customizable website for publishing your API documentation where consumers can discover APIs, learn how to use them, request access, and try them out. The content hasn't been published yet. You can do so in "Developer portal" section of your API Management Service in the Azure portal. Learn more."

Permissions:

We are performing all actions using accounts that have both Global Administrator and Cloud Application Administrator roles. The issue occurs with both roles.

What we have already tried:

  • Multiple publish attempts (including after waiting 10–15 minutes between tries)
  • Refreshing the portal page
  • Checking the Activity Log for any detailed error (no specific error message is shown beyond “failed”)
  • Verifying that the APIM instance is in a healthy/running state

Could you please help us troubleshoot why the Developer Portal publish is failing? Any diagnostics, known issues, workarounds, or additional logs we should check would be greatly appreciated.

We can provide:

  • Subscription ID
  • APIM service name / resource group
  • Exact error details from the portal (if visible in the browser console or activity log)
  • Screenshots of the failure

Thank you in advance for your support!

Best regards,Hi Microsoft Support Team,

We are facing a persistent issue with our Azure API Management service where we cannot publish the Developer Portal.

Issue Summary:

  • The APIM service deploys successfully.
  • Backend APIs are working correctly (we have tested them and they respond as expected).
  • However, every time we try to publish the Developer Portal (from the Azure portal → API Management service → Developer portal section → Publish button), the operation fails.
  • After each failed publish attempt, the Developer Portal still shows the default “unpublished” page with the following message:

"This is a home page of the Developer portal - an automatically generated, fully customizable website for publishing your API documentation where consumers can discover APIs, learn how to use them, request access, and try them out. The content hasn't been published yet. You can do so in "Developer portal" section of your API Management Service in the Azure portal. Learn more."

Permissions:

We are performing all actions using accounts that have both Global Administrator and Cloud Application Administrator roles. The issue occurs with both roles.

What we have already tried:

  • Multiple publish attempts (including after waiting 10–15 minutes between tries)
  • Refreshing the portal page
  • Checking the Activity Log for any detailed error (no specific error message is shown beyond “failed”)
  • Verifying that the APIM instance is in a healthy/running state

Could you please help us troubleshoot why the Developer Portal publish is failing? Any diagnostics, known issues, workarounds, or additional logs we should check would be greatly appreciated.

We can provide:

  • Subscription ID
  • APIM service name / resource group
  • Exact error details from the portal (if visible in the browser console or activity log)
  • Screenshots of the failure

Thank you in advance for your support!

Best regards,

Azure API Management
Azure API Management

An Azure service that provides a hybrid, multi-cloud management platform for APIs.

1 answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. Pravallika KV 15,465 Reputation points Microsoft External Staff Moderator
    2026-04-10T09:05:14.7166667+00:00

    Hi Shahzad Muhammad,

    Thanks for reaching out to Microsoft Q&A.

    What Publishing Does Under the Hood

    1. The portal’s admin UI calls your APIM management endpoint (GET contentTypes/document/contentItems/configuration) to pull down the saved content.
    2. It writes that content into the portal storage and pushes it to the front-end CDN.
    3. You get a success/failure status back in the Azure portal.

    Below are the common reasons it fails:

    • Permissions gap for portal token generation
    • VNet or DNS blocking management calls
    • Untrusted TLS cert on a custom domain
    • Unsaved design changes

    Troubleshooting Steps & Checks:

    1. Verify Browser Console & Correlation ID
      • Open F12, go to Network, reproduce the publish.
      • Look for failing calls to …/contentItems/configuration?api-version=…
      • Grab any HTTP status, error text or correlation ID.
    2. RBAC Permission for Portal Admin
      • Even Global Admin/Azure AD Admin roles need the Microsoft.ApiManagement/service/users/token/action permission at the APIM service scope.
      • You can create or assign the built-in “APIM New Portal Admin” custom role (see FAQ below).
      • After assigning, sign out/in and retry.
    3. VNet & DNS (if APIM is in an internal VNet)
      • Can your client machine resolve the management endpoint’s internal VIP?
      • Try curl https://<your-apim>.management.azure-api.net/... from the same network.
      • If you front-end APIM with an App Gateway/WAF, ensure you’ve allowed traffic to the management endpoint.
    4. Custom Domain & Cert Trust
      • If you bound a custom domain (portal or mgmt), the browser must trust the TLS certificate.
      • As a quick test, remove the custom mgmt domain and republish to fall back on the default endpoint.
    5. Save in Design Mode
      • Any Design-mode edits (themes, widgets, identity providers) require you to click Save before you hit Publish.
    6. Check Diagnostic Logs
      • Enable APIM diagnostic logs in Azure Monitor, filter for contentItems operations and look for failures.
    7. Try a Different Browser/Incognito
      • IE isn’t supported. Make sure you’re on a current version of Chrome/Edge/Firefox/Safari.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.