This chapter covers the Azure API Management Developer Portal, a fully customizable, self-service portal for API consumers. The portal is a key component of Azure API Management and is tested under objective 5.1 (Integrate with API Management) of the AZ-204 exam. Approximately 10-15% of exam questions touch on API Management features, with a subset specifically on the Developer Portal. Understanding its capabilities, customization options, and integration with backend APIs is critical for passing the exam.
Jump to a section
Imagine a large retail store that sells tools for building furniture. The store has a showroom (the Developer Portal) where customers can browse products, read manuals, and see pricing. Behind the scenes, there is a warehouse (the API Management service) that holds all the actual products. Customers cannot enter the warehouse directly; they must go through the store's ordering process. The Developer Portal is like the showroom: it displays product catalogs (API documentation), allows customers to sign up for a loyalty card (subscription), and provides a shopping cart (API key generation). When a customer finds a tool they like, they take a product code (endpoint URL) and a membership card (subscription key) to the checkout counter (API Gateway) to complete the purchase (make an API call). The store also has a community bulletin board (forum) where customers share tips and report issues. Without the showroom, customers would have to wander into the warehouse, which is dangerous and inefficient. The Developer Portal makes the API discoverable, understandable, and usable, just as a showroom makes products accessible without exposing the entire inventory.
What is the API Management Developer Portal?
The Developer Portal is an automatically generated, fully customizable website that serves as the primary interface for API consumers. It provides documentation, interactive test consoles, subscription management, and analytics. The portal is built on a modern, responsive framework (based on Paperbits) and can be extended with custom HTML, CSS, and JavaScript. It is designed to replace the deprecated legacy developer portal.
Why It Exists
APIs are useless if developers cannot discover, understand, and test them. The Developer Portal solves these problems by: - Discoverability: Listing all published APIs in one place. - Documentation: Auto-generating interactive API reference docs from OpenAPI/Swagger definitions. - Self-service: Allowing developers to sign up, create subscriptions, and obtain API keys without manual intervention. - Testing: Providing a built-in test console to call APIs directly from the portal. - Education: Hosting tutorials, code samples, and forums.
How It Works Internally
The Developer Portal is a single-page application (SPA) hosted within the API Management service. It retrieves content from a built-in content management system (CMS) that stores pages, media, and layouts. When a user visits the portal, the browser loads the SPA, which then fetches content via API calls to the API Management management plane. The portal supports both anonymous and authenticated access. Authentication is handled via Azure AD or other identity providers configured in the portal's settings.
The portal content is stored as a set of entities in the API Management service. These entities include: - Pages: HTML content with optional Markdown. - Media: Images, CSS, JavaScript files. - Layouts: Templates that define the overall structure. - Navigation: Menu items linking to pages.
Key Components, Values, Defaults, and Timers
Portal URL: https://<service-name>.developer.azure-api.net (default). You can also assign a custom domain.
Portal versions: There are two versions: the legacy portal (deprecated) and the new portal (current). The new portal is built on Paperbits and is fully customizable.
Content storage: The portal content is stored in the API Management service's internal database. You can export/import content as a .zip file using the portal's management interface or the REST API.
Authentication: Supported identity providers include Azure AD, Azure AD B2C, Facebook, Google, Twitter, Microsoft Account, and generic OAuth 2.0.
Subscription keys: Developers can generate primary and secondary keys for each subscription. Keys are 32-character strings.
Rate limiting: Policies can be applied to enforce rate limits per subscription.
CORS: The portal itself does not require CORS, but APIs accessed from the test console may need CORS policies.
Configuration and Verification Commands
To deploy the portal via Azure CLI:
az apim portal deploy --resource-group myGroup --service-name myApim --portal-name newTo get the portal URL:
az apim portal show --resource-group myGroup --service-name myApim --query portalUrlTo enable CORS for the portal on an API:
az apim api policy set --resource-group myGroup --service-name myApim --api-id myApi --policy <path-to-policy.xml>Policy snippet for CORS:
<cors allow-credentials="true">
<allowed-origins>
<origin>https://myapim.developer.azure-api.net</origin>
</allowed-origins>
<allowed-methods>
<method>*</method>
</allowed-methods>
<allowed-headers>
<header>*</header>
</allowed-headers>
</cors>How It Interacts with Related Technologies
API Management Gateway: The portal interacts with the gateway indirectly. When a developer uses the test console, the API call is made from the browser to the gateway, which then forwards to the backend. The portal itself does not proxy API calls; it only provides a UI.
Azure AD: For authentication, the portal redirects users to Azure AD login. The portal configuration stores the client ID and tenant ID.
OpenAPI/Swagger: The portal imports API definitions from OpenAPI 2.0/3.0 files. It generates documentation and test console automatically.
GitHub: The portal can be configured to sync content with a GitHub repository for version control.
Logic Apps / Power Automate: The portal can embed custom widgets that call Logic Apps or Power Automate flows.
Customization Options
The portal is highly customizable. You can:
Modify the theme (colors, fonts) via the visual editor.
Add custom pages with HTML/Markdown.
Create custom widgets using React or Vue.
Override the default templates for API documentation.
Use the management REST API to programmatically manage content.
Performance and Scale
The portal is a static SPA, so it loads quickly. Content is cached via CDN (Azure Front Door or a CDN of your choice). The portal can handle thousands of concurrent users. The API Management service itself has scale limits (e.g., 500 requests per second for Developer tier), but the portal is not directly affected by these limits since it only serves static content and makes management API calls.
Security Considerations
Enable authentication to restrict portal access to authorized developers.
Use custom domains with TLS to ensure secure connections.
Apply policies to APIs to enforce authentication and rate limiting.
Regularly update the portal content and apply security patches.
Common Pitfalls
Forgot to deploy the portal: The portal must be explicitly deployed after creation.
CORS errors: The test console may fail if the API does not allow CORS from the portal domain.
Subscription key leaks: Ensure keys are not exposed in client-side code.
Custom domain misconfiguration: DNS records must point to the API Management endpoint.
Create API Management instance
First, you need an Azure API Management service instance. This is the parent resource that hosts the Developer Portal. You can create it via the Azure portal, CLI, or ARM template. The portal is automatically provisioned but not deployed. The default URL is `https://<service-name>.developer.azure-api.net`. Ensure you choose a tier (Developer, Basic, Standard, Premium) that supports the portal. The Developer tier is free but limited in scale.
Enable and deploy the portal
By default, the portal is not deployed. You must explicitly deploy it. In the Azure portal, go to your API Management instance, select 'Developer portal' under 'Portal overview', and click 'Deploy'. Alternatively, use the CLI command `az apim portal deploy`. Deployment takes a few minutes. After deployment, the portal is accessible at the default URL. The portal content is initially empty except for default pages like 'Home', 'APIs', and 'Products'.
Customize portal appearance
The portal includes a visual editor for customization. You can change the theme (colors, fonts), upload a logo, and modify the layout. Click 'Edit' on the portal to enter the editor. The editor allows you to modify pages, media, and navigation. You can also add custom HTML/CSS/JS. Changes are saved as drafts and must be published to go live. The portal uses a WYSIWYG editor for pages and a code editor for advanced customizations.
Add APIs and products
APIs must be imported into the API Management instance to appear in the portal. You can import OpenAPI specs, create APIs manually, or use Azure services (e.g., Function Apps). APIs are grouped into Products. Products control visibility and subscription requirements. For example, a 'Starter' product might be free and require no approval, while a 'Premium' product requires admin approval. Each product can have multiple APIs. Developers subscribe to products to get subscription keys.
Configure authentication
To allow developers to sign in, configure an identity provider. In the portal editor, go to 'Settings' > 'Authentication'. You can enable Azure AD, Azure AD B2C, or social logins. For Azure AD, you need to register an application in Azure AD and provide the client ID and tenant ID. The portal redirects users to the identity provider for login. After successful authentication, users can manage their subscriptions and see their API keys.
Publish the portal
After making changes, you must publish them to make them live. In the portal editor, click 'Publish'. This action overwrites the live portal with the current draft. You can also schedule publishing or use version control with GitHub. Publishing is immediate. The portal URL remains the same.
Enterprise Scenario 1: Fintech API Marketplace
A bank wants to expose its payment APIs to third-party developers. They use API Management with the Developer Portal. The portal is customized with the bank's branding and provides interactive documentation for each API. Developers must register and get approval for specific products (e.g., 'Payments' product). The portal enforces rate limits: 100 calls per minute for the free tier, 1000 for premium. The bank uses Azure AD B2C for authentication, allowing developers to sign in with their corporate accounts. The portal is deployed across multiple regions using Premium tier for high availability. Misconfiguration: Initially, CORS was not enabled, causing the test console to fail with 403 errors. The fix was to add a CORS policy on all APIs allowing the portal domain.
Enterprise Scenario 2: Healthcare API Provider
A healthcare company provides FHIR APIs to partners. They use the Developer Portal to host documentation and a sandbox environment. The portal is customized with custom widgets that show real-time API health status. They sync portal content with a GitHub repository for version control. Developers can test APIs using sample patient data. The portal uses OAuth 2.0 with Azure AD for authentication. Scalability: The portal handles 5000 concurrent users during peak hours. They use Azure Front Door as a CDN to cache static content. A common issue: developers forget to include the subscription key in requests, so the portal shows a warning message in the test console.
Enterprise Scenario 3: E-commerce Platform
A large e-commerce company exposes product catalog and order APIs. They use the Developer Portal to allow third-party sellers to integrate. The portal includes a forum and a blog for announcements. They have multiple environments: dev, test, and production. Each environment has its own API Management instance and portal. They use the REST API to automate content deployment. Performance: The portal loads in under 2 seconds due to CDN caching. They monitor portal usage with Application Insights. A common misconfiguration: the custom domain SSL certificate expires, causing browser warnings. They set up automated certificate renewal using Key Vault.
What AZ-204 Tests on This Topic
AZ-204 objective 5.1 focuses on integrating with API Management. Specific sub-objectives include: creating API Management instances, configuring APIs, managing products and subscriptions, and customizing the Developer Portal. The exam expects you to know:
How to deploy the portal (it is not deployed by default).
How to configure authentication (Azure AD, Azure AD B2C, social).
How to customize the portal (themes, pages, custom widgets).
How to publish content.
How to use the test console and how CORS affects it.
Common Wrong Answers
'The portal is automatically deployed when you create the API Management instance.' This is false. You must explicitly deploy it.
'You can only use Azure AD for authentication.' False. You can use multiple identity providers including social logins.
'The portal requires a custom domain to work.' False. It works with the default *.developer.azure-api.net domain.
'You cannot customize the portal code; only the theme.' False. You can add custom HTML, CSS, and JavaScript, and even build custom widgets.
Specific Numbers and Terms
Default portal URL: https://<service-name>.developer.azure-api.net
Subscription key length: 32 characters
Portal deployment command: az apim portal deploy
CORS policy element: <cors>
Identity provider configuration: in portal settings under 'Authentication'
Edge Cases and Exceptions
Portal not accessible: If the portal returns 404, it may not be deployed. Deploy it.
Test console fails: Likely CORS issue. Ensure the API has a CORS policy allowing the portal domain.
Custom domain not working: DNS must point to the API Management gateway endpoint (not the developer portal endpoint). The portal uses a different hostname.
Authentication loop: If Azure AD is misconfigured (wrong client ID or tenant), users may be redirected in a loop.
How to Eliminate Wrong Answers
If a question asks about deploying the portal, look for 'deploy' or 'publish' actions. Options that say 'automatically available' are wrong.
For authentication, any option that restricts to only one provider is usually wrong because the portal supports multiple.
For customization, any option that says 'no custom code' is wrong.
For CORS, remember the test console is client-side and needs CORS. If the question mentions test console failures, think CORS.
The Developer Portal must be explicitly deployed after creating an API Management instance.
The portal supports multiple identity providers for developer authentication, including Azure AD, Azure AD B2C, and social logins.
Customization includes themes, pages, navigation, and custom HTML/CSS/JS; custom widgets can be built with React or Vue.
The test console makes direct API calls from the browser, so CORS policies must be configured on APIs to allow the portal domain.
Portal content can be exported/imported as a .zip file and synced with GitHub for version control.
The default portal URL is https://<service-name>.developer.azure-api.net; custom domains are optional.
Changes to the portal must be published to go live; the editor uses a draft/publish model.
Subscription keys are 32-character strings; developers can generate primary and secondary keys.
These come up on the exam all the time. Here's how to tell them apart.
Legacy Developer Portal
Deprecated; no longer recommended for new deployments.
Built on ASP.NET MVC, less customizable.
Limited to basic theme changes (colors, logo).
Not responsive by default; mobile experience poor.
No support for custom widgets or modern JavaScript frameworks.
New Developer Portal
Current and actively developed; recommended for all new instances.
Built on Paperbits, a modern SPA framework.
Fully customizable with visual editor and custom code.
Responsive design; works on mobile devices.
Supports custom widgets using React, Vue, or plain JavaScript.
Mistake
The Developer Portal is automatically deployed and ready to use when you create an API Management instance.
Correct
The portal is provisioned but not deployed. You must explicitly deploy it via the Azure portal, CLI, or REST API.
Mistake
The portal only supports Azure AD for developer authentication.
Correct
The portal supports multiple identity providers including Azure AD, Azure AD B2C, Facebook, Google, Twitter, Microsoft Account, and generic OAuth 2.0.
Mistake
You cannot customize the portal beyond changing the theme and logo.
Correct
The portal allows full customization including custom HTML, CSS, JavaScript, and custom widgets built with React or Vue.
Mistake
The test console in the portal does not require CORS because API Management handles the request server-side.
Correct
The test console runs in the browser and makes direct API calls to the gateway, so CORS must be enabled on the APIs if the portal domain is different from the API domain.
Mistake
You must use a custom domain for the Developer Portal.
Correct
Custom domains are optional. The portal works out of the box with the default `*.developer.azure-api.net` domain.
Reveal each answer, then mark whether you got it right. Score 60%+ to unlock the next chapter.
Deploy the portal using the Azure portal: go to your API Management instance, select 'Developer portal' under 'Portal overview', and click 'Deploy'. Alternatively, use the CLI command `az apim portal deploy --resource-group myGroup --service-name myApim`. The portal is not deployed by default. After deployment, it is accessible at `https://myApim.developer.azure-api.net`.
Yes, you can configure a custom domain. In the Azure portal, under your API Management instance, go to 'Custom domains' and add a domain for the 'Developer portal' type. You must also upload a TLS certificate and update DNS records to point to the API Management gateway endpoint. Note that the custom domain must be different from the gateway domain.
In the portal editor, go to 'Settings' > 'Authentication'. You can enable one or more identity providers. For Azure AD, you need to register an application in Azure AD and provide the client ID, tenant ID, and optionally the client secret. For social logins, you need to obtain app IDs and secrets from the provider. After configuration, developers can sign in using their chosen identity.
The test console runs in the browser and makes API calls directly to the API Management gateway. If the API does not have a CORS policy allowing the portal domain, the browser blocks the request. To fix this, add a CORS policy to the API (or all APIs) with an `<allowed-origins>` element that includes the portal domain (e.g., `https://myApim.developer.azure-api.net`).
You can add custom HTML, CSS, and JavaScript to any page. For more advanced customization, create custom widgets using React or Vue. The portal supports embedding widgets via the 'Custom widget' feature. You can also override the default templates for API documentation by editing the 'API' page layout. All changes are saved as drafts and must be published.
No, by default, APIs require a subscription key. However, you can configure APIs to not require a subscription by setting the 'Subscription required' option to false in the API's settings. This is useful for open APIs. If you disable subscription requirement, the test console will not prompt for a key.
In the portal editor, click on 'Export' under the 'Content' menu. This downloads a .zip file containing all pages, media, and templates. You can later import this .zip file into another API Management instance using the 'Import' button. You can also set up continuous export to a GitHub repository for version control.
You've just covered API Management Developer Portal — now see how well it sticks with free AZ-204 practice questions. Full explanations included, no account needed.
Done with this chapter?