Adding New Rate Limiting Policies¶

WSO2 API Manager admins can add new rate limiting policies and define extra properties to the rate limiting policies. To get started, click on the level of rate limiting that you want to add a new policy to:

Adding New Rate Limiting Policies
Adding a new advanced rate limiting policy
Adding a new application-level rate limiting tier
Adding a new subscription-level rate limiting tier

Adding a new advanced rate limiting policy¶

You can add advanced rate limiting policies to both APIs and resources.

Sign in to the Admin Portal using the URL https://localhost:9443/admin and your admin credentials (admin/admin by default).
Click Advanced Throttling under the Rate Limiting Policies section to see the set of existing rate limiting tiers.
To add a new tier, click Add New Policy.
Fill in the required details and click Add.

Note

Rate limiting based on request count or bandwidth

Request Count and Request Bandwidth are the two options for default limit. You can use the option according to your requirement. Request Count is commonly used as the limiting option for API requests. If you are using APIs for File sharing and Data transmission you can use Request Bandwidth as your default limiting option.

To add rate limiting limits with different parameters to the conditions below, click Add Conditional Group.

Note

Enabling header, query param or JWT based rate limiting

IP based throttling is enabled by default.
Note that if you want to add a header, query param, or JSON Web Token (JWT) claim condition, you need to set the enable_header_based_throttling , enable_jwt_claim_based_throttling or enable_query_param_based_throttling element to true (depending on which condition you need) under [apim.throttling] in the repository/conf/deployment.toml file.
This JWT is the backend JWT and not the one you use to invoke it. In addition, you need to enable the Backend JWT token to get this rate limiting flow to work.

You can add a description about the condition group by click Description under Condition Group.

Condition	Description value
IP Condition	Allows you to set a rate limiting limit for a specific IP address or a range of IP addresses.
Header Condition	Allows you to set a rate limiting limit to specific headers and parameters.
Query Param Condition	Allows you to set a rate limiting limit to specific query parameters.
JWT Claim Condition	Allows you to set a rate limiting limit to specific claims.

Note

Conditional group evaluation

The conditional group execution policy is used only for that condition. For example, if you add an IP condition and set the request count as shown in the above diagram, only 5 requests will be allowed per minute using that IP condition. The default limit will be applied for any request that evaluates to false with that condition (Outside that condition).

Enter a condition and value.

Note

The IP-based advanced rate limiting expects the client IP in the X-Forwarded-For header, in order to detect the IP address and throttle out the request as specified in the IP condition configuration.
Header condition and JWT claim condition values allow regex patterns to be defined. You can configure it to make either an exact match or a pattern match for the value using the regex values. For example:
Note

JWT condition

Claim name : Name of the JWT Claim Example:
- "iss" - The issuer of the JWT
- " http://wso2.org/claims/apicontext - Context of the API
- " http://wso2.org/claims/version - API version
Claim value : Value to be checked in the corresponding claim. (allows regex patterns as well)

Invert condition : Whether to take the throttle decision based on the equality of the values. Example: If the claim name is "iss" value is "wso2" and "invert condition" is off - Requests having "wso2" as "iss" claim will be throttled. If the claim name is "iss" value is "wso2" and "invert condition" is on - Requests not having "wso2" as "iss" claim will be throttled.
Once done, click Add.

You have added a new advanced rate limiting policy. You can now apply it to an API or a resource.

Note

Adding multiple conditional groups

You can configure multiple conditional groups when defining a tier for advanced rate limiting policies. For example, it is possible to apply both an IP based rate limiting and a query parameter condition in a single advanced policy.

Adding a new application-level rate limiting tier¶

Application-level rate limiting policies are applicable per access token generated for an application.

Sign in to the Admin Portal using the URL https://localhost:9443/admin and your admin credentials (admin/admin by default).
Click Application Policies under the Rate Limiting Policies section to see the set of existing rate limiting tiers.
To add a new tier, click Add Policy.
Fill in the required details and click Save.

You have added a new application-level rate limiting policy.

Adding a new subscription-level rate limiting tier¶

Sign in to the Admin Portal using the URL https://localhost:9443/admin and your admin credentials.
Click Subscription Policies under the Rate Limiting Policies section. The existing set of rate limiting tiers are displayed.
To add a new tier, click Add Policy.

Note

Unauthenticated tier

When you are adding a new Subscription level rate limiting tier, you will see the existing list of subscription tiers in the Subscription Tier List. In this list, you will find a tier named Unauthenticated, which has a request quota of 500. This is the subscription tier, which is automatically applied when the authentication type of your resources is 'None'. That is when you can invoke APIs without tokens. And this tier is not visible in the rate limiting tier list of the application.

Note

It is not recommended to modify the default Unlimited subscription tier. If required, you can create a separate subscription tier to represent the existing Unlimited tier and do the modifications accordingly.

Fill in the details required by this form and click Save once you are done.

Request bandwidth based quota limits

Event Based (AsyncAPI) quota limits

Note

Event Based (Async API) - These configurations are applicable to all the Streaming APIs (WebSocket, SSE, and WebHook (WebSub) APIs).
WebHooks - This is only applicable to the WebHook (WebSub) APIs

Given below are the descriptions of the fields you find in the form:

Field	Description
Request Count/Request Bandwidth/Event Count	The maximum number of requests/maximum bandwidth/maximum events allowed to the API within the time period given in the next field.
Unit Time	Time within which the number of requests given in the previous field is allowed to the API. This can be defined in minutes, hours, days, weeks, months or years.
Burst Control (Rate Limiting)	You can define the request count/bandwidth per unit time on an addition layer by using rate limiting. This is usually a smaller number of requests/bandwidth for a shorter time span than what is enforced in the above fields. For instance, if there's a subscription level policy enforced over a long period, you may not want users to consume the entire quota within a short time span. Enforcing a rate limit protects the backend from sudden request bursts and controls the usage at a subscription and API level.
GraphQL	Provide the maximum complexity and maximum depth values for GraphQL APIs using this policy.
WebHooks	Maximum number of WebHooks allowed for a WebHooks API using this policy.
Stop On Quota Reach	This indicates the action to be taken when a user goes beyond the allocated quota. If the check box is selected, the user's requests are dropped and an error response (HTTP Status code 429) is given. If the check box is cleared, the requests are allowed to pass through.
Billing Plan	This field only makes sense if you have API Monetization enabled. The available billing plans are Free, Commercial, and Freemium. An API is tagged/labelled as Free, Paid, or Freemium depending on its subscription tiers(e.g., Unlimited, Gold, etc.), which are the tiers selected when creating an API.
Custom Attributes	You can choose to display additional information about tiers using custom attributes during custom implementations. The main objective of these fields are to provide more information regarding the tier to Application Developers at the time of API subscription. An example usage of custom attributes is API Monetization. See Enabling Monetization of APIs- for more information on practical usage of custom attributes in the subscription tier.
Permissions	You can allow or deny permission for specific roles. Once permission is denied to a role, the new subscription tier that you add here will not be available to that role in the Developer Portal.

Note

Billing plan

Free - If all subscription tiers are defined as Free, the API uses the Free billing plan and the API is labeled as Free in the Developer Portal. Paid - If all subscription tiers are defined as Paid, the API uses the Commercial billing plan and the API is labeled as Paid in the Developer Portal.
Freemium - If the API has a combination of Free and Paid subscription tiers, the API uses the Freemium billing plan and the API is labeled as Freemium in the Developer Portal.

This labeling happens on the Developer Portal only if monetization has been enabled. For information on how to enable monetization and how to tag subscription tiers, see Configuring API Monetization Category Labels.

You have now successfully added a new subscription-level rate limiting policy.