Creating Governance Rules

This document explains different types of governance rules and how to create them.

For a general overview on governance rules and its use cases, see Introduction to Quotas and Governance. To know how to manage your existing governance rules, see Managing Governance Rules.

Types of Rules

Moesif supports two kinds of governance rules, both suited to a specific use case. These types include:

  • Behavior Rules
  • Quota Rules

Governance is incompatible with the Tyk, Azure APIM, and AWS API Gateway integrations. Check with your customer success representative if governance is supported for your server integration.

Behavior Rules

A Behavior Rule allows you to target specific populations based on certain criteria. In general, defining a Behavior Rule involves two steps:

  1. Define your target user segment using a user or company cohort.
  2. Define the governance rule you want to enforce on the target user segment.

Each behavioral governance rule can only target one type of cohort at a time. You cannot define a behavioral governance rule that targets both a user cohort and a company cohort. Rules without any cohorts apply to all users and companies.

By default, Moesif restricts all kinds of access to your API from users or companies that match the governance rule. To refine what you want to block, use regular expressions. This allows you to define regular expressions on API requests so that you can block only parts of your API.

For instructions on how to define behavior rules, see Create Behavior Rules.

Quota Rules

With Quota Rules, you can restrict customers based on subscription plans and prices. Quota Rules allow you to define quotas and limits under a subscription scheme. When subscribers exceed a quota, Moesif enforces the rule on them and restricts access to your API.

Similar to Behavior Rules, Moesif, by default, restricts all kinds of access to your API from subscribers who match the rule. To refine what you want to block, use regular expressions to define regular expressions on API requests so that you can block only parts of your API.

For instructions on how to define quota rules, see Create Quota Rules.

Create Behavior Rules

  1. Select Quotas & Governance from the navigation menu and then select + Add New. Alternatively, select + New and then select Gov Rule/Quota. Quotas & Governance Rules screen. Some elements are highlihted to show different ways to create a governance rule.
  2. Select Start from Blank Behavior Rule.
  3. Specify a name for your rule in the Governance Rule Name field.
  4. Select one or more cohorts to which you want to apply the rule. The Select cohorts to apply rule list shows existing user and company cohorts. You can create a new cohort by selecting + Create a New User Cohort or + Create a New Company Cohort from the list.
  5. Optionally, select Block What and specify regular expressions to tune further what you want to block.
  6. In the Respond With pane, specify overrides for response status and body. You can optionally also override response headers. You must override the response status and body for a blocking rule.
  7. Optionally, set the priority for your rule.
  8. Select Create.

For example, the following shows a user rule to block API access to users with overdue invoices. The rule also lets them know that the reason for blocking is paused subscription.

An example governance rule called 'Block Users With Unpaid Invoices'.

Choose How To Apply a Rule to a Cohort

When defining a behavior rule, you can apply the rule inclusively or exclusively to the one or more cohorts you select. You can set this by choosing the are or are not filter when you select the user or company cohort for your rule.

If you choose the are filter, the rule applies whenever a user or company belongs to the specified cohort. For example, you may create a rule that blocks all users on a specific subscription tier if they exceed their quota.

If you choose the are not filter, the rule applies to every user or company not belonging to the specified cohort. For example, you want to block every user who does not have an active subscription from accessing your APIs. Therefore, you may have a cohort named “Users With Active Subscriptions” containing all users with valid subscriptions. If you choose this cohort when defining your rule and select the are not filter, the criteria becomes Apply to Customer that are not members of Users cohorts below. Then, Moesif blocks every user without an active subscription from accessing your APIs.

Apply Cohort to Unidentified Users

You can choose to apply a cohort for events that don’t have associated user IDs by selecting Apply to Unidentified Users. For example, consider a user with user ID 1234 who is in the cohort “Users With Active Subscriptions”. With this
option disabled, Moesif applies the cohort only for events that has the associated user ID 1234. If you enable this option, then Moesif applies the cohort even for events that don’t have any associated user IDs.

Blocking and Non-blocking

A blocking rule means Moesif actively blocks the customer’s requests before they reach your upstream service. Moesif also overrides the response HTTP status and body according to your rule configuration. To set a rule to block, select the Blocking further access checkbox.

For a non-blocking rule, the request continues to your upstream service. Moesif only overrides any HTTP response headers but doesn’t change the HTTP body and status code. To set a rule to non-blocking, clear the Blocking further access checkbox.

For a blocking rule, you must override the HTTP status and body.

Override Response Status

For a blocking rule, you must override the HTTP response status code by selecting a status from the Response Status Override list. The “Block Users With Unpaid Invoices” rule sets the status to 402 Payment Required.

Override Response Headers

You can override any number of HTTP response headers by selecting Add Header. If the upstream service has already set a header, Moesif overrides the existing one. Otherwise, Moesif adds new headers.

Override Response Body

For a blocking rule, you must override the HTTP response body that the client receives in the Response Body Override field. This supports merge tags from the user or company profile. The “Block Users With Unpaid Invoices” rule adds an error message explaining to the user why they are blocked. The rule also mentions the user’s subscription plan that has overdue invoices.

Set rule priority

You can optionally set a priority for your rule in the Priority field. User cohort rules take higher priority than company cohort rules. However, within a group of user rules, you can prioritize between 0 and 100. A lower number means higher priority.

Create Quota Rules

To create a Quota Rule, follow these steps:

  1. Select Quotas & Governance from the navigation menu and then select + Add New. Alternatively, select + New and then select Gov Rule/Quota. Quotas & Governance Rules screen. Some elements are highlihted to show different ways to create a governance rule.
  2. Select Start from Blank Quota Rule.
  3. Specify a name for your rule in the Governance Rule Name field.
  4. Specify the subscription provider, plan, and price.
  5. In the Block When pane, specify the quota.
  6. Optionally, select Block What and specify regular expressions to tune further what you want to block.
  7. In the Response When Blocking pane, specify overrides for response status and body. Quota rules are always blocking so you must override the response status and body. Optionally, you can also override response headers.
  8. Optionally, set the priority for your rule.
  9. Select Create.

Specify Quota

When you create a quota rule, you must specify a subscription provider, plan, and optional price. After that, open the Show matching subscribers pane. This pane shows the matching subscribers in tabular format. The table shows each matching subscriber’s company ID, subscription ID, and last seen time.

After narrowing down your target subscribers, specify the quota you want to enforce. For example, you can define a quota that blocks subscribers after they exceed 10,000 API calls in the current billing month.

To define a quota, follow these steps:

  1. In the Block When pane, specify the API event details you want Moesif to monitor. Moesif blocks subscribers from accessing your API whenever their behavior matches the event details you specify. For example, to block subscribers in the current plan after they exceed 10,000 API calls, do the following:

    a. Select API Call as the event type.

    b. Specify 10000 as the event count.

    c. Select Calendar Month as the event period.

  2. Open the Show subscribers over quota pane. It shows the company ID, subscription ID, and last seen time for each matching subscriber who has exceeded the quota.

An example quota rule that blocks current subscribers after 10,000 API calls.

Blocking and Non-blocking

A blocking rule means Moesif actively blocks the customer’s requests before they reach your upstream service. Moesif also overrides the response HTTP status and body according to your rule configuration. Quota rules are always blocking, so you must override the HTTP response status and body.

Override Response Status

You must override the HTTP response status code for each quota rule by selecting a status from the Response Status Override list.

Override Response Headers

You can override any number of HTTP response headers by selecting Add Header. If the upstream service has already set a header, Moesif overrides the existing one. Otherwise, Moesif adds new headers.

Override Response Body

For each quota rule, you must override the HTTP response body that the client receives in the Response Body Override field. This supports merge tags from the user or company profile.

Set rule priority

You can optionally set a priority for your rule in the Priority field. User cohort rules take higher priority than company cohort rules. However, within a group of user rules, you can prioritize between 0 and 100. A lower number means higher priority.

Use Regular Expressions

Both behavioral and quota governance rules support regular expressions to define restrictions explicitly. This allows you to control further what parts of your API you want to block.

To use regular expressions, follow these steps when you create a governance rule:

  1. Open the Block What pane.
  2. Select the request field you want to apply your regular expression to—for example, Request Verb.
  3. Enter your regular expression criteria. For example, if you choose Request Verb in the preceding step, you can enter post as your regular expression. This causes Moesif to block HTTP POST requests.

Highlighting the 'Block What' pane that allows using regular expressions.

You can combine multiple regular expressions by selecting Or Group or + Regex Criteria.

Create Rules With Governance Rule Templates

After you create a new governance rule, the dialog contains several template rules from which you can start. These allow you to set up governance rules for popular use cases quickly.

To create and use a template, select one and then select Continue. Then you can further customize the rule.

Governance rule templates to choose from.

Moesif includes the following governance rule templates:

When you create a template, it performs the following tasks automatically:

  1. Creates the applicable cohorts to match the rules.
  2. Adds them to a new governance rule.
  3. Configures other parameters in the rule to match the use case. This includes any HTTP status code and JSON response body.

Block Inactive Subscriptions

A behavioral rule that blocks users if they do not have an active subscription in your configured billing providers.

Block on Unpaid Invoices

A behavioral rule that blocks users trying to access your APIs with any overdue or unpaid invoices from your configured billing providers.

Block When No Available Credits

A behavioral rule that blocks users who have run out of pre-paid credits on your configured billing providers.

Block Sending More Than a Hundred Megabytes Per Hour

A behavioral rule that blocks any user who has sent more than 100 MB in the last hour. The calculation follows the sum of the Content-Length header in each request.

Block Downloading More Than a Hundred Megabytes Per Hour

A behavioral rule that blocks any user who has downloaded or received more than 100 MB in the last hour. The calculation follows the sum of the Content-Length header in each request.

Updated: