Developer Portal Customisation

Developer Portal Overview

The developer portal is an automatically generated, fully customisable website for API consumers. It serves as the primary interface where developers discover, learn about, and subscribe to your APIs.

Microsoft Reference: Developer portal overview

Default Features

Out of the box, the developer portal provides:

Feature	Description
API Catalogue	Browse and search available APIs
Interactive Documentation	Try APIs directly in the browser
Subscription Management	Request, view, and manage subscription keys
User Registration	Self-service sign-up and profile management
API Specifications	View OpenAPI/Swagger definitions
Code Samples	Auto-generated code snippets in multiple languages
Usage Analytics	View personal API usage statistics
Product Pages	Discover API bundles and their terms

Accessing the Portal

URL	Purpose
https://{apim-name}.developer.azure-api.net	Live portal (published)
https://{apim-name}.portal.azure-api.net	Admin portal (edit mode)
Custom domain	Via CNAME DNS record

Customisation

Visual Editor

1. Navigate to the Developer Portal section in the Azure Portal
2. Click Developer portal to open the admin interface
3. Use the visual drag-and-drop editor to modify:
   • Pages and navigation
   • Layout and widgets
   • Styles and branding
   • Content (text, images, videos)
4. Click Publish to make changes live

Branding and Styling

Customise the portal appearance through the Styles editor:

/* Custom CSS variables available in the portal */
:root {
  --portal-brand-color: #0078D4;
  --portal-brand-color-dark: #005A9E;
  --portal-text-color: #333333;
  --portal-background-color: #FFFFFF;
  --portal-link-color: #0078D4;
  --portal-font-family: 'Segoe UI', sans-serif;
  --portal-heading-font-family: 'Segoe UI Semibold', sans-serif;
}

Customisation options include:

• Logo — Upload company logo for the header
• Favicon — Custom browser tab icon
• Colour scheme — Primary, secondary, and accent colours
• Typography — Font families, sizes, and weights
• Footer — Custom footer content and links
• CSS overrides — Custom CSS for fine-grained control

Custom Pages

Create custom pages for:

• Getting started guides
• Authentication tutorials
• SDKs and client libraries
• Changelog and release notes
• Terms of service and privacy policy
• Contact and support information
• FAQs and troubleshooting

Microsoft Reference: Customise the developer portal

Widgets

Built-in Widgets

Widget	Description
Text	Rich text content with markdown support
Image	Image display with alt text
Button	Call-to-action buttons
API List	Catalogue of available APIs
API Details	Individual API documentation
Operation	API operation details and test console
Code Snippet	Auto-generated code samples
Subscription List	User's active subscriptions
Product List	Available products
Navigation	Site navigation menu
Search	API and content search

Custom Widgets

Create custom HTML/JavaScript widgets for bespoke functionality:

// custom-widget/index.ts
import { widgetModuleId, buildOnChange } from "@azure/api-management-custom-widgets-tools";

export async function initialize() {
  const container = document.getElementById("custom-widget-container");

  // Your custom widget logic
  const response = await fetch("/api/custom-data");
  const data = await response.json();

  container.innerHTML = `
    <div class="custom-dashboard">
      <h3>API Health Status</h3>
      <ul>
        ${data.apis.map(api => `
          <li class="status-${api.status}">
            ${api.name}: ${api.status}
          </li>
        `).join('')}
      </ul>
    </div>
  `;
}

Microsoft Reference: Create custom widgets

User Management

Authentication Providers

Provider	Configuration
Username/Password	Built-in, default option
Azure Active Directory	Enterprise SSO
Azure AD B2C	Consumer identity management
Delegation	Custom authentication flow

Azure AD Integration

resource apimIdentityProvider 'Microsoft.ApiManagement/service/identityProviders@2023-05-01-preview' = {
  parent: apim
  name: 'aad'
  properties: {
    type: 'aad'
    clientId: aadAppClientId
    clientSecret: aadAppClientSecret
    allowedTenants: [tenantId]
    signinTenant: tenantId
    authority: 'login.microsoftonline.com'
  }
}

Azure AD B2C Integration

For external developer portals with consumer sign-up:

resource apimB2CProvider 'Microsoft.ApiManagement/service/identityProviders@2023-05-01-preview' = {
  parent: apim
  name: 'aadB2C'
  properties: {
    type: 'aadB2C'
    clientId: b2cAppClientId
    clientSecret: b2cAppClientSecret
    allowedTenants: [b2cTenantName]
    signinTenant: '${b2cTenantName}.onmicrosoft.com'
    authority: '${b2cTenantName}.b2clogin.com'
    signupPolicyName: 'B2C_1_signup_signin'
    signinPolicyName: 'B2C_1_signup_signin'
    profileEditingPolicyName: 'B2C_1_profile_edit'
    passwordResetPolicyName: 'B2C_1_password_reset'
  }
}

Microsoft Reference: Developer portal authentication

User Groups

Group	Description	Default Members
Administrators	Full portal access and management	Subscription administrators
Developers	Authenticated portal users	Auto-assigned on sign-up
Guests	Unauthenticated visitors	Anonymous users

Create custom groups for fine-grained access:

resource partnerGroup 'Microsoft.ApiManagement/service/groups@2023-05-01-preview' = {
  parent: apim
  name: 'partners'
  properties: {
    displayName: 'Partner Developers'
    description: 'External partner developers with access to partner APIs'
    type: 'custom'
  }
}

Self-Hosted Developer Portal

For full customisation control, self-host the developer portal:

When to Self-Host

• Custom authentication not supported by built-in providers
• Complex custom widgets or integrations
• Specific hosting requirements (CDN, WAF, custom domain rules)
• Content management workflow requirements
• Complete visual override requirements

Setup

# Clone the developer portal repository
git clone https://github.com/Azure/api-management-developer-portal.git
cd api-management-developer-portal

# Install dependencies
npm install

# Configure connection to your APIM instance
# Edit src/config.design.json and src/config.publish.json

# Run locally for development
npm start

# Build for production
npm run publish

# Deploy to Azure Storage Static Website or Azure App Service
az storage blob upload-batch \
  --source ./dist \
  --destination '$web' \
  --account-name stdevportal

Microsoft Reference: Self-host the developer portal

Custom Domain

Configure a custom domain for the developer portal:

resource portalDomain 'Microsoft.ApiManagement/service/portalconfigs@2023-05-01-preview' = {
  parent: apim
  name: 'default'
  properties: {
    enableBasicAuth: false
    signin: {
      require: false
    }
    signup: {
      termsOfService: {
        requireConsent: true
        text: 'I agree to the terms of service.'
        enabled: true
      }
    }
  }
}

// Custom domain configuration
resource customDomain 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: apim.name
  location: location
  properties: {
    hostnameConfigurations: [
      {
        type: 'DeveloperPortal'
        hostName: 'developers.enterprise.com'
        certificateSource: 'KeyVault'
        keyVaultId: 'https://kv-enterprise.vault.azure.net/secrets/dev-portal-cert'
      }
      {
        type: 'Proxy'
        hostName: 'api.enterprise.com'
        certificateSource: 'KeyVault'
        keyVaultId: 'https://kv-enterprise.vault.azure.net/secrets/api-cert'
      }
    ]
  }
}

Content Management via API

Manage portal content programmatically:

# List portal content
az rest --method GET \
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{apim}/contentTypes?api-version=2023-05-01-preview"

# Export portal content (for backup or migration)
az rest --method POST \
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{apim}/portalRevisions?api-version=2023-05-01-preview" \
  --body '{"properties": {"description": "Backup before update"}}'

Email Notifications

Configure email templates for developer communications:

Template	Trigger
Welcome	New user registration
Subscription Approved	Subscription request approved
Subscription Rejected	Subscription request rejected
Password Reset	User requests password reset
Close Account	Account deletion request
New Issue	User submits a support issue

Microsoft Reference: Email templates

Best Practices

1. Publish regularly — Changes in the admin portal are not visible until published
2. Use Azure AD for enterprise developer portals to leverage existing identities
3. Customise branding to match your organisation's visual identity
4. Create getting started guides — reduce time-to-first-call for new developers
5. Enable subscription approval for production APIs to control access
6. Set up email notifications to keep developers informed
7. Use custom domains with SSL for a professional appearance
8. Test portal changes in the admin view before publishing
9. Backup portal content before making major changes
10. Monitor portal usage via Application Insights to understand developer behaviour

Official Microsoft Resources

• Developer portal overview
• Customise the portal
• Self-host the portal
• Configure Azure AD sign-in
• Configure Azure AD B2C
• Custom widgets
• Email notifications