This documentation is for WSO2 API Manager 2.1.0. View documentation for the latest release.

All docs This doc

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: ✉️ IP Whitelisting on APIM 2.1.0 not behaving accordingly


  1. Login to API Publisher https://<IP_address>:9443/publisher.
  2. Edit API and go to Manage tab.
  3. Enable Apply to API under Advance Throttling Policies and select the newly created Throttling policy.
  4. Save and Publish the API.
    Now the API will be accessible only by the IP specified in the throttling policy.


    Since it takes some time to deploy the policy, the first few requests from the IPs other than the white-listed IP/IPs will be passed through. After the policy is successfully deployed, non-white-listed IP access will be blocked.


    API-M Throttling is asynchronous. When you apply a new whitelisting condition, note that at least one request has to go through for the condition to be applied

Blacklisting requests

By blacklisting requests, you can protect servers from common attacks and abuse by users. For example, if a malicious user misuses the system, all requests received from that particular user can be completely blocked. Tenant administrative users can block requests based on the following parameters:

  • Block calls to specific APIs
  • Block all calls from a given application
  • Block requests coming from a specific IP address
  • Block a specific user from accessing APIs

To blacklist a request, 

  1. Log in to the Admin Portal using the URL https://localhost:9443/admin and your admin credentials.
  2. Click Black List under the Throttle Policies section and click Add Item.
  3. Select the item to black list, enter a value and click Blacklist.


Note that you have to use "/" always infront of the ${context} value when blacklisting the APIs with API context. E.g. /test/1.0.0. The sample provided in the product does not include "/" due to a known issue.


You can temporary on/off the blacklisting condition by enabling/disabling the Condition status that is auto enabled when a blacklisting condition is created.

Blacklisting PhoneVerification API

As described above you can blacklist requests for APIs, by Applications, to IP Addresses and for Users. Let's see how we can blacklist the requests come to the PhoneVerification API that we published in Quick Start Guide.

  1. Log in to the Admin Portal using the URL https://localhost:9443/admin and your admin credentials.
  2. Click Black List under the Throttle Policies section and click Add Item.
  3. Select API Context and provide the Context of PhoneVerification API with version as the Value.
  4. Click Blacklist.
  5. Now login to API Store using the URL https://localhost:9443/store and invoke the API.
    You will see the following response.

Custom throttling

Custom throttling allows system administrators to define dynamic rules for specific use cases, which are applied globally across all tenants. When a custom throttling policy is created, it is possible to define any policy you like. The Traffic Manager acts as the global throttling engine and is based on the same technology as WSO2 Complex Event Processor (CEP), which uses the Siddhi query language. Users are therefore able to create their own custom throttling policies by writing custom Siddhi queries. The specific combination of attributes being checked in the policy need to be defined as the key (also called the key template). The key template usually includes a predefined format and a set of predefined parameters. It can contain a combination of allowed keys separated by a colon (:), where each key must start with the prefix $. The following keys can be used to create custom throttling policies:

resourceKey, userId, apiContext, apiVersion, appTenant, apiTenant, appId 

For example, the following sample custom policy allows the admin user to send 5 requests per minute to the Pizza Shack API. 

Code Block
titleKey Template
Code Block
titleSiddhi query
FROM RequestStream
SELECT userId, ( userId == '[email protected]'  and apiContext == '/pizzashack/1.0.0' and apiVersion == '1.0.0') AS isEligible ,
str:concat('[email protected]',':','/pizzashack/1.0.0:1.0.0') as throttleKey
INSERT INTO EligibilityStream;
FROM EligibilityStream[isEligible==true]#window.time(1 min)
SELECT throttleKey, (count(throttleKey) >= 5) as isThrottled group by throttleKey
INSERT ALL EVENTS into ResultStream;

As shown in the above Siddhi query, the throttle key must match the key template format. If there is a mismatch between the key template format and the throttle key, requests will not be throttled.