Securing and mediating APIs is a critical function for any API developer. The most frequent methods to secure an API is based on OAuth/OpenID Connect with (or without) Client Id/Secret, which are standard interfaces defined in an Open API specification. Mediation of an API is done within the API Gateway and is unique for each gateway implementation. API Connect provides API mediation via its API Assembly which includes out-of-the box policies to mediate API transactions, including programmatic extensibility via JavaScript (called GatewayScript) and XSLT.  An API assembly is compromised of one or more policies, pipelined together to secure and mediate API payloads before sending the request to a backend service.

Modernizing business workloads can be a challenge since new modern security techniques don’t integrate with traditional or legacy implementations. The DataPower API Gateway can help mediate between security protocols and bridge legacy applications with modern digital interfaces. In this article, you will explore several techniques to create and manage API policies.


The API Assembly supports User-Defined Policies that provide flexibility to package API Assembly policies into a single policy for reusability and governance. Furthermore, combined with a new GatewayScript API to invoke any DataPower rule object, it gives you the ability to access any function available within the DataPower Gateway!

In general, you will need to create User Defined Policies (UDP) for the API Gateway in one of the following situations:

  1. Reusable UDP: Package existing API Assembly policies into a single reusable policy that is shared across multiple developers or the enterprise. In this scenario, you don’t need access to DataPower Gateway functionality exposed in the DataPower UI.
  2. UDP for Managed DataPower Objects: Create a UDP when a policy needs access to a Datapower object. For example, when you need to use an MQ queue manager or SQL Datasource in a GatewayScript or XSLT policy. In this scenario, you need access to the DataPower UI for creating the specific object(s).
  3. UDP for DataPower rule: Create a UDP that uses DataPower functionality such as AAA policy for functionality that is not available in the API Assembly (eg SAML Generate). In this scenario, you need access to the DataPower UI to create the DataPower rule that is invoked via the UDP policy.

The complexity of each type of policy increases (from #1 to #3), including your expected knowledge of DataPower Gateway functionality. In the next section, we will examine each type of UDP policy.

User-Defined Policies (UDP)  Types

Basic UDP

The repository shows a sample DataPower configuration file and GatewayScript that you can customize based on your own requirements. The equivalent API Assembly actions used are the Set-Variable and GatewayScript policies. If you need other API assembly actions, you will need the equivalent DataPower configuration. More details on how to obtain this configuration will be provided later in the article.

You can easily reuse this UDP policy example, replace all instances of udp-basic with the name of your policy. Furthermore, modify the GatewayScript file with your logic. If you open up udp-basic-policy.cfg file, search for the string $(local.parameter.credential) . This parameter is used to pass runtime parameters that the API Developer enters when configuring your API Assembly. It can be used to drive dynamic behavior.

UDP For Managed DataPower Objects

The repository shows how to use a DataPower managed object from GatewayScript and XSLT policies. These objects must be created when you want to use functionality that is not available in the API assembly but exists within the DataPower Gateway.

You can write GatewayScript/XSLT to connect to an MQ queue manager and SQL Datasource, but the code requires access to an existing DataPower managed object. The configuration for these objects can be packaged within the Gateway Extension and the name needs to be used within the code. For example, in the snippet below, IBM_Cloud_QM is the name of an existing DataPower MQ Queue Manager object, which must be defined when the code is executed.

var options = { target: 'dpmq://' + 'IBM_CLOUD_QM' + '/?'

UDP for DataPower rule

This repository shows how to create a UDP policy that invokes a Datapower rule. You will need to use GatewayScript and the multistep module to call an existing DataPower processing rule. The creation of a DataPower multi-step rules is outside the scope of the article. The Datapower rule must also be packaged as DataPower configuration. You can find several examples of UDP policies in the repository for the token generation use case. Several GatewayScript files are packaged in the repository, you only need to focus on the <udp-policy>-call-rule.js and <udp-policy>-aaa-credential.js files. They will need to be modified to reflect the parameter names that you want to expose in the UDP p0licy.


Several options exist for packing User-defined policies, using either Gateway Extensions or individual UDP deployment. If your running on Kubernetes, you can package UDPs using the instructions here. In this article, we will show how to package them via Gateway Extensions. This approach is easier since all your UDPs and any referenced files exist within the API Manager so that  deployment across a cluster of API Gateways is managed whether your on Kubernetes or OVA. The API Manager includes the Gateway Extension CLI to store the Gateway Extension within the API Manager so you can perform managed deployments into the gateway cluster.

When deploying a Gateway Extension, consider the following:

  • A single Gateway extension is deployed to a Gateway cluster. Artifacts are packaged into a ZIP file containing .cfg files, together with any dependent files that are referenced from the CFG file.
  • All files must be at the root of the ZIP file. The CFG files are processed in alphanumeric order by file name.
  • ZIP files are uploaded to the file system: local:///filestores/extensions/gateway-extension/ so any file references within UDP must be adjusted accordingly.

DataPower configuration packaged into a UDP must be in the form of CLI commands, for both managed Datapower objects or DataPower rules. The DataPower UI provides the ability to import / export ZIP files but support for CFG is not available yet. My recommendation would be to copy the exact DataPower CLI commands from the DataPower file system (config:///<domain>.cfg. You can find the appropriate commands based on the naming convention. Place the CLI commands into the appropriate file, following conventions in the provided examples.

Once the Gateway extensions are deployed, they should appear in the API Assembly editor and you can use them like any out-of-the box policy in the API designer.


In this article, you learned how to create User-defined policies that allow you to extend the behavior of the API Gateway, enabling reuse and accelerating API development. Three types of UDPs are available, based on your requirements, ranging from simple reusable API assembly policies to leveraging DataPower managed objects and rules. Use Gateway extensions to package your UDPs and deploy them across a Gateway cluster, also making them available within the API designer.

8 comments on"Building User-Defined Policies on the API Gateway"

  1. I am having a user defined policy and I need to import this in my api manager. Below are the commands that I have run,
    1. Command: apic login –username userid –password password –server mgmt_endpoint_url –realm mode/realm
    Response: Logged into mgmt_endpoint_url successfully
    2. Command: apic policies:create -c catalog –configured-gateway-service gateway -o organization -s –scope scope
    Response: Error: Unauthorized

    How do I proceed?

  2. I would check the API manager logs. Can you try another userid with higher privileges to validate if its an issue with your permissions?

    I would suggest you post your question on a forum where you can get help from the wider community:

  3. Hi, I have tried the “udp-basic” sample. Two questions please.
    After the CLI step “gateway-extensions:create” how the zip content (cfg, js) is applied/activated?
    I added the UDP in the drop-down menu in API Connect Gateway Service Object and dis-/enabled the Gateway Service.
    But after starting the API Designer the UDP is not visible in the Palette? Do I miss something?
    Regards Uli

  4. The “gateway-extensions:create” copies the contents of the extension to each DataPower Gateway. You don’t need to manually create UDP objects since the config should be part of the gateway extension.

    Check the logs if you don’t see the UDP in the API Designer. I would disable/enable the API Connect Service object again to make sure that the logic to send the policies to the palette is triggered.

  5. The `api policies` command only supports the v5c gateway. We are planning to add support for User Defined Policies for the API Gateway in the near future. This is the reason why I took the approach of using gateway extensions to upload policies.

  6. Hi, Some help will be appreciated with the questions below:

    Is this compatible with Datapower API Gateway? (seems the answer is “no”)

    How is this implemented => “Reusable UDP: Package existing API Assembly policies into a single reusable policy …”
    Again the question, is this only on Datapower Gateway? but the text says “…you don’t need access to DataPower Gateway functionality exposed in the DataPower UI…”

    We are trying to bundle and set a number of Datapower API Gateway policies from the APIm Assemble into a single, enforced policy.

  7. Yes, the steps in this document absolutely support the API Gateway service. The nuance discussed in the previous comment is that the CLI for uploading **just** user defined policies is not supported; however, you can accomplish the same by using the CLI for gateway extensions.

    If you simply want to package existing Assembly, you can follow the steps outlined in the document and don’t need to create additional datapower rule objects via the DataPower UI.

  8. Hi, Thank you for the article. Please help to answer below question
    Currently in V5.x we have a GW extension that rewrites the Client_ID/Client_Secret headers to X-IBM-Client-Id/X-IBM-Client-Secret using a datapower processing rule(xslt), and also import an MQ Manager Object. Can this be achived in the APIGateway Extension(V2018)? or should we use Global Policies? Please advise.

Join The Discussion

Your email address will not be published. Required fields are marked *