Custom Policies

If you want an API policy that isn’t included in the default set of policies, you can create your own custom policy. A custom policy requires the following files:

  • Policy Definition - YAML file that describes the policy and its configurable parameters

  • Policy Configuration - XML file with the backend processes that implement the policy

A custom policy also must contain a pointcut declaration. See the Pointcuts Reference below for more information.

You can create a custom policy if you use one of the following runtimes:

  • Mule 3.8 or later unified runtime

  • API Gateway runtime 2.x or later

In Studio 6.1 and later, you can use the Studio custom policy editor (Beta).


Custom policies must be self-contained. From a custom policy, do not reference another dependent policy, a connector on the app, a shared connector or any other dependency that could be available at runtime or in an external library.

You create a custom policy by using the elements in Mule Runtime to evaluate and process HTTP calls and responses. The policy filters calls to an API and matches one of the query parameters in the request to a configurable, regular expression. Unmatched requests are rejected. You set the HTTP status and the payload to indicate an error whenever a request does not match the conditions of the filter.

Applying a Custom Policy

To make a custom policy available to users, you add the policy to Anypoint Platform in API Manager. On the API version details page of an API, users can then choose Policies, select the custom policy from the list, and apply the policy to the API.

If you deploy the API on a private server using a .zip file that you downloaded from Anypoint Platform, the new policy is available for on-premises users to apply. Even if the proxy was already deployed before creating the policy, there’s no need to re-download or re-deploy anything. The new policy automatically downloads to the /policies folder, in the location where the API Gateway or Mule 3.8 unified runtime is installed. Configure your organization’s Client ID and Token in the wrapper.conf file.

Failed Policies

In Mule Runtime 3.8 and later and API Gateway Runtime 2.1 and later, when an online policy is malformed and it raises a parse exception, it’s stored under failedPolicies directory inside policies directory, waiting to be reviewed. In the next poll for policies it won’t be parsed. If you delete that policy, it is deleted from that folder too. If the folder has no policies, it is deleted.

Using Existing Policies

You can modify or combine existing policies that exist by default. You can view the XML source code, and use it in a custom policy configuration.

In an on-premises runtime installation, search for the folder examples>policies to find existing policies.

Was this article helpful?

💙 Thanks for your feedback!

Submit your feedback!
Share your thoughts to help us build the best documentation experience for you!
Take our latest survey!