Configure Azure API Management Integration


This information applies to SwaggerHub On-Premise 1.20.0 and later.

To use the Azure API Management integration, you first need to configure an application in Azure that will authenticate requests from your SwaggerHub instance to the Azure platform.


  • Your company must have an Azure Active Directory (Azure AD) tenant. Many companies have existing tenants as part of Microsoft services (such as Microsoft 365) or Azure subscriptions.

  • Your SwaggerHub On-Premise instance must be on HTTPS. Make sure HTTPS is configured, and the SSL Termination setting in the Admin Center is set to either Use SSL with termination on SwaggerHub (certificate required) or Use SSL with termination on external load balancer.

Register an application in Azure

  1. Sign in to the Azure portal at

  2. Select Azure Active Directory from the portal sidebar.

  3. Select App registrations and click New registration.

    Registering a new application in Azure
  4. Specify the following settings:

    • NameSwaggerHub

    • Supported account types – Select one of the following, depending on which Microsoft account types your company uses:

      • Accounts in any organizational directory

      • Accounts in any organizational directory and personal Microsoft accounts (e.g. Skype, Xbox,

      Accounts in any organizational directory
    • Redirect URI – Select Web and specify the following value, replacing SWAGGERHUB with your SwaggerHub On-Premise domain:

  5. Click Register.

  6. Note down the Application (client) ID – you will need it later.

    Azure client ID
  7. Select Certificates & secrets and click New client secret.

    Creating a new client secret for an Azure application
  8. Set Expires to Never, enter a description for this client secret, and click Add.

    Client secret configuration
  9. Copy the generated client secret as you will not see it later.

    Azure client secret
  10. Select API permissions and click Add a permission.

    Adding permissions to an application in Azure
  11. Select Azure Service Management.

    Azure Service Management
  12. Select the user_impersonation check box and click Add permissions.

    Adding the user_impersonation permission

Configure SwaggerHub

  1. Open the Admin Center.

  2. Select Settings > Integrations on the left.

  3. In the Azure API Management Client ID and Azure API Management Client Secret fields, specify the Azure client ID and the client secret you created earlier.

  4. Click Save Changes and Restart. Wait a few minutes for the system to restart completely.

Verify the configuration

  1. Open an existing API definition or create a new one (for example, Petstore).

  2. Click the API name, switch to the Integrations tab, and click Add New Integrations.

  3. Select Azure API Management. This will open the integration settings screen.

  4. You should see the Sign in with Microsoft button at the bottom of the integration settings screen:

    Sign in with Microsoft


    If the "Sign in with Microsoft" image does not appear, make sure you access SwaggerHub using the correct domain name or IP that matches the DNS name for this server value specified in the Admin Center.

    SwaggerHub On-Premise domain
  5. Click Sign in with Microsoft. You should be redirected to Azure and prompted to log in and grant the permissions required by the integration.


    If the Azure login screen shows an error instead, see the troubleshooting tips below.

    Sign in with Microsoft

If the "Sign in with Microsoft" button works, you can proceed to configure the Azure API Management integration for your API definitions.


AADSTS50011: The reply url specified in the request does not match the reply urls configured for the application

  • Make sure that SwaggerHub’s SSL Termination setting is set to Use SSL.

  • In the Azure portal, go to Azure Active Directory > App registrations > (click your application) > Authentication. Make sure that Redirect URI has Type=Web and the value is set to https://SWAGGERHUB/apiproxy/plugins/configurations/oauthWithState (with SWAGGERHUB replaced with your domain name).

AADSTS50194: Application is not configured as a multi-tenant application. Usage of the /common endpoint is not supported for such applications created after '10/15/2018'. Use a tenant-specific endpoint or configure the application to be multi-tenant.

In the Azure portal, go to Azure Active Directory > App registrations > (click your application) > Authentication and make sure that Supported account types are Accounts in ANY organizational directory, and not Accounts in THIS organizational directory only. If this option has a wrong value, delete the existing Azure application and create a new one as explained above. Remember also to update the Azure client ID and secret in the SwaggerHub Admin Center.

AADSTS650057: Invalid resource. The client has requested access to a resource which is not listed in the requested permissions in the client's application registration.

In the Azure portal, go to Azure Active Directory > App registrations > (click your application) > API permissions and add a permission for Azure Service Management > user_impersonation.

See Also

Publication date: