API Management developer portal - frequently asked questions
What if I need functionality that isn't supported in the portal?
You have the following options:
For small customizations, use a built-in widget to add custom HTML .
For larger customizations, create and upload a custom widget to the managed developer portal.
Self-host the developer portal, only if you need to make modifications to the core of the developer portal codebase.
Open a feature request in the GitHub repository.
Learn more about customizing and extending the functionality of the developer portal.
Can I have multiple developer portals in one API Management service?
You can have one managed portal and multiple self-hosted portals. The content of all portals is stored in the same API Management service, so they will be identical. If you want to differentiate portals' appearance and functionality, you can self-host them with your own custom widgets that dynamically customize pages on runtime, for example based on the URL.
Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?
No.
Is the portal's content saved with the backup/restore functionality in API Management?
No.
Do I need to enable additional VNet connectivity for the managed portal dependencies?
In most cases - no.
If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. The management endpoint's host name must resolve to the internal VIP of the service from the machine you use to access the portal's administrative interface. Make sure the management endpoint is registered in the DNS. In case of misconfiguration, you will see an error: Unable to start the portal. See if settings are specified correctly in the configuration (...).
If your API Management service is in an internal VNet and you're accessing it through Application Gateway from the internet, make sure to enable connectivity to the developer portal and the management endpoints of API Management. You may need to disable Web Application Firewall rules. See this documentation article for more details.
I assigned a custom API Management domain and the published portal doesn't work
After you update the domain, you need to republish the portal for the changes to take effect.
I added an identity provider and I can't see it in the portal
After you configure an identity provider (for example, Microsoft Entra ID, Azure AD B2C), you need to republish the portal for the changes to take effect. Make sure your developer portal pages include the OAuth buttons widget.
I set up delegation and the portal doesn't use it
After you set up delegation, you need to republish the portal for the changes to take effect.
My other API Management configuration changes haven't been propagated in the developer portal
Most configuration changes (for example, VNet, sign-in, product terms) require republishing the portal.
I'm getting a CORS error when using the interactive console
The interactive console makes a client-side API request from the browser. Resolve the CORS problem by adding a CORS policy on your API(s).
You can check the status of the CORS policy in the Portal overview section of your API Management service in the Azure portal. A warning box indicates an absent or misconfigured policy.
Note
Only one CORS policy is executed. If you specified multiple CORS policies (for example, on the API level and on the all-APIs level), your interactive console may not work as expected.
Automatically apply the CORS policy by clicking the Enable CORS button.
You can also enable CORS manually.
- Select the Manually apply it on the global level link to see the generated policy code.
- Navigate to All APIs in the APIs section of your API Management service in the Azure portal.
- Select the </> icon in the Inbound processing section.
- Insert the policy in the <inbound> section of the XML file. Make sure the <origin> value matches your developer portal's domain.
Note
If you apply the CORS policy in the Product scope, instead of the API(s) scope, and your API uses subscription key authentication through a header, your console won't work.
The browser automatically issues an OPTIONS HTTP request, which doesn't contain a header with the subscription key. Because of the missing subscription key, API Management can't associate the OPTIONS call with a Product, so it can't apply the CORS policy.
As a workaround you can pass the subscription key in a query parameter.
What is the CORS proxy feature and when should I use it?
Select the Use CORS proxy option in the configuration of the API operation details widget to route the interactive console's API calls through the portal's backend in your API Management service. In this configuration, you no longer need to apply a CORS policy for your APIs, and connectivity to the gateway endpoint from the local machine isn't required. If the APIs are exposed through a self-hosted gateway or your service is in a virtual network, the connectivity from the API Management's backend service to the gateway is required. If you use the self-hosted portal, specify the portal's backend endpoint using the backendUrl option in the configuration files. Otherwise, the self-hosted portal won't be aware of the location of the backend service.
What permissions do I need to edit the developer portal?
If you're seeing the Oops. Something went wrong. Please try again later. error when you open the portal in the administrative mode, you may be lacking the required permissions (Azure RBAC).
The portal requires the permission Microsoft.ApiManagement/service/users/token/action at the scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.
You can use the following PowerShell script to create a role with the required permission. Remember to change the <subscription-id> parameter.
#New Portals Admin Role
Import-Module Az
Connect-AzAccount -Environment AzureChinaCloud
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor"
$customRole = $contributorRole
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin"
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator"
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action"
$customRole.IsCustom = $true
$customRole.AssignableScopes.Clear()
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>')
New-AzRoleDefinition -Role $customRole
Once the role is created, it can be granted to any user from the Access Control (IAM) section in the Azure portal. Assigning this role to a user will assign the permission at the service scope. The user will be able to generate SAS tokens on behalf of any user in the service. At the minimum, this role needs to be assigned to the administrator of the service. The following PowerShell command demonstrates how to assign the role to a user user1 at the lowest scope to avoid granting unnecessary permissions to the user:
New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1"
After the permissions have been granted to a user, the user must sign out and sign in again to the Azure portal for the new permissions to take effect.
I'm seeing the Unable to start the portal. See if settings are specified correctly (...) error
This error is shown when a GET call to https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview fails. The call is issued from the browser by the administrative interface of the portal.
If your API Management service is in a VNet, refer to the VNet connectivity question.
The call failure may also be caused by an TLS/SSL certificate, which is assigned to a custom domain and is not trusted by the browser. As a mitigation, you can remove the management endpoint custom domain. API Management will fall back to the default endpoint with a trusted certificate.
What's the browser support for the portal?
| Browser | Supported |
|---|---|
| Apple Safari | Yes1 |
| Google Chrome | Yes1 |
| Microsoft Edge | Yes1 |
| Microsoft Internet Explorer | No |
| Mozilla Firefox | Yes1 |
1 Supported in the two latest production versions.
Local development of my self-hosted portal is no longer working
If your local version of the developer portal cannot save or retrieve information from the storage account or API Management instance, the SAS tokens may have expired. You can fix that by generating new tokens. For instructions, refer to the tutorial to self-host the developer portal.
How do I disable sign-up in the developer portal?
If you don't need the sign-up functionality enabled by default in the developer portal, you can disable it with these steps:
In the Azure portal, navigate to your API Management instance.
Under Developer portal in the menu, select Identities.
Delete each identity provider that appears in the list. Select each provider, select the context menu (...), and select Delete.
Navigate to the developer portal administrative interface.
Remove Sign up links and navigation items in the portal content. For information about customizing portal content, see Tutorial: Access and customize the developer portal.
Modify the Sign up page content to remove fields used to enter identity data, in case users navigate directly to it.
Optionally, delete the Sign up page. Currently, you use the contentItem REST APIs to list and delete this page.
Save your changes, and republish the portal.
How can I remove the developer portal content provisioned to my API Management service?
Provide the required parameters in the scripts.v3/cleanup.bat script in the developer portal GitHub repository, and run the script
cd scripts.v3
.\cleanup.bat
cd ..
How do I enable single sign-on (SSO) authentication to self-hosted developer portal?
Among other authentication methods, the developer portal supports single sign-on (SSO). To authenticate with this method, you need to make a call to /signin-sso with the token in the query parameter:
https://contoso.com/signin-sso?token=[user-specific token]
Generate user tokens
You can generate user-specific tokens (including admin tokens) using the Get Shared Access Token operation of the API Management REST API.
Note
The token must be URL-encoded.
Next steps
Learn more about the developer portal:
- Access and customize the managed developer portal
- Extend the functionality of the developer portal.
- Set up self-hosted version of the portal
Browse other resources: