Creating Governance Rules

With governance, you can create rules that automatically enforce quotas or restrict access to your APIs. For example, if you are monetizing your API with a prepaid billing model, you can create a governance rule to block access when a customer’s balance goes below zero dollars. You can also use governance to protect your APIs such as to block scraping an abnormally large amount of data from your API.

Accessing Governance Rules

To access governance rules, click on Governance Rules in the left-side navigation menu.

Accessing Governance

To easily create a new Governance Rule, click the Create New button and select Governance Rule

Accessing Governance

It’s important to remember that newly created governance rules are set to “off” by default. They must be turned to “on” in order to be enabled.

Types of rules

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

Cohort-Based Rules

If you have a specific cohort or multiple cohorts that you’d like to apply a rule to, this can be done by selecting the applicable cohorts from the Applicable Cohort(s) dropdown. Initially you will see a list of all user and company cohorts. Once a cohort has been selected, the list will only show either company-level or user-level cohorts since you cannot mix and match the different cohort types.

By picking a user cohort(s), you’ll be defining a user rule. A user rule is one that is applied to all users that is a member of a behavioral cohort. You can create behavioral cohorts that match any criteria and behavior such as API access patterns, customer demographics, and more.

Examples of ways to leverage user rules include:

  • “Block users with many 401 unauthorized errors in last 7 days”
  • “Block users who accessed over 100 items in an hour”

By picking a company cohort, you’ll be defining a company rule. A company rule is very similar to a user rule except it blocks an entire company. Examples of ways to leverage company rules include: If a request matches both a user and company rule, the user rule takes priority.

  • “Block companies with overdue invoices”
  • “Block companies who exceeded plan quotas”

For both types of rules, you can also add regex criteria so your rule only applies to specific requests.

Regex Rule

Unlike user and company rules, regex rules apply to all API requests regardless if the request was authenticated. This enables blocking or applying goverernace for specific URIs, status codes, and more. Example of regex rules include:

  • “Add a X-API-Warn deprecation header for all requests to /v1/old”
  • “Block all requests to /my-super-secret-endpoint

Choosing how to apply a rule to a cohort (Apply to X in aove cohort(s))

When defining your rule, you can choose to apply the rule inclusively or exclusively to a given cohort. This can be set by choosing Apply to Users/Companies in above cohorts or Apply to Users/Companies NOT in above cohorts from the radio selector.

If you choose Apply to Users/Companies in above cohorts, the rule will be applied whenever a user/company belongs to the selected cohort(s). For example, you may create a rule that blocks all users on a specific subscription tier if they go over their allocated quota.

If you choose Apply to Users/Companies NOT in above cohorts , the rule will be applied to every user/company who DOES NOT belong to the selected cohort(s). An example of this may be that you want to block every user from accessing your APIs that does not have an active subscription. For instance, I may have a cohort named Users With Active Subscriptions that contains all users who have a valid subscription. If I were to choose this as my Applicable User/Company Cohort and select Apply to Users/Companies NOT in above cohorts, every user without an active subscription would be blocked from accessing the APIs.

Creating a rule

To create a new rule, navigate to the Governance Rules screen and click the Add New button. From the dropdown, select New User Rule or New Company Rule if you want to block specific customers based on behavior.

If you want to only govern based on request info regardless of the customer behavior (such as unauthenticated requests), select New Regex Rule.

Add new governance rule

Let’s walk through an example creating a User Rule to block API access to companies with overdue invoices. We also want to let them know that they are blocked due to their subscription being paused.

Block API Access to Users with Overdue Invoices

Once the rule is created, by clicking Create in the top right corner of the Create New Governance Rule screen, you’ll need to insure that the rule is turned on. By default, a new governance rule is not enabled.

Enable the new governance rule

Apply To Companies/Users

These are the saved cohorts that you want to apply the rule to.

A saved cohort is a dynamic list of users (or companies) that performed some behavior in terms of API calls and user actions. You can also match on any custom metadata you store with the profiles such as subscription or billing info. New cohort rules can be created from user lookup or company lookup panel.

For metered billing quota rules

If you are looking to apply governance for subscription enforcement, you will want to set up the cohort to keep track of events within the customers billing period. In this case, you will set your cohort filter and make sure you use one of the following values that can bucket results based on the user/company’s billing start and end dates:

  • Current Monthly Billing Period
    • This will only factor in events that have happened in the user/company’s current monthly billing period.
  • Last Monthly Billing Period
    • This will only factor in events that have happened in the user/company’s last billing period that has already passed.
  • Current Billing Term
    • This will only factor in events that have happened in the user/company’s current term. If their term is quarterly or yearly, this will show all of the events within that term. For monthly, it will display the same as the Current Monthly Billing Period option.

This can be especially useful for anyone using Moesif for API monetization since Governance Rules can be created from cohorts to control access to an API based on a users subscription terms. For example, you may create a governance rule where a users subscription tier only allows them to consume 10,000 API calls per month. By using the options above, specifically Current Monthly Billing Period in this case, cohorts can now be created to accurately ensure that users stay within their limits during based on their unique billing period start and end dates.

Regex Criteria

By default, the rule will apply to all requests from customers in your target cohorts. You can selectively enable the rules for specific requests regex rules such as a specific URI.

Blocking vs Non-blocking

If a rule is blocking, this means Moesif will actively block the customer’s requests before getting to your upstream service. Moesif will also override the response HTTP status and body to whatever the rule is configured for.

If a rule is non-blocking, this means the request will still continue to your upstream service. Moesif will only override any HTTP response headers, but will leave the body and status code alone (passthrough).

Override Response Status

If set to blocking, this enables a way to override the response status such as an error code. In this example, we set it to 429 Payment Required

Override Response Headers

You can override any number of HTTP response headers. If the header was already set by the upstream service, Moesif will override the existing one. Otherwise, Moesif will add new headers.

Override Response Body

If set to blocking, you can override the body that will be responded to the client. This supports merge tags from the user or company profile. In our example, we add an error message explaining to the user why they are blocked. We also mentioned which plan they are on that has overdue invoices.

Creating rules using Governance Rule Templates

When you click Add New on the Governance Rules main screen, the modal that appears will have various rules that can be created from a template.

Start governance rule from template

For convenience, you can choose from some convenient templates that allow you to set up Governance Rules for popular use cases quickly. Current templates that Moesif supports include:

  • Block Inactive Subscriptions
    • For metered billing, this rule will block users if they do not have an active subscription in your configured billing providers.
  • Block on Unpaid Invoices
    • Also for metered billing, this rule will block any users trying to access your APIs with any overdue/unpaid invoices from your configured billing providers.
  • Block When No Available Credits
    • For prepaid and PAYG metered billing, this rule will block users that have run out of pre-paid credits on your configured billing providers.
  • Block Sending > 100MB/hr
    • This rule will block any user that has sent more than 100MB in the last hour (as calculated by the sum of the Content-Length header in each request)
  • Block Downloading > 100MB/hr
    • This rule will block any user that has downloaded/received more than 100MB in the last hour (as calculated by the sum of the Content-Length header in each response)

Each template will automatically create the applicable cohorts to match these rules, add them to a new Governance Rule, and configure other parameters in the rule to match the use case (including any status code and JSON response body). Once created, these rules can be customized further if needed.

Updated: