Sign in →
1 min read

MuleSoft Integration (Custom Policy)

Apply the Aforo Custom Policy via Anypoint Exchange. Global enforcement across all APIs without modifying Mule flows.

Updated 2026-07-29Suggest edits

Task Overview#

JIRA-READY TASK
Apply the Aforo Custom Policy via Anypoint Exchange.
Estimated time: 25 minutes. Target: MuleSoft Platform Architect.

Why Custom Policy?#

MuleSoft is the most complex enterprise gateway estate. Aforo integrates via a Custom Policy — the MuleSoft-native extension mechanism that enforces logic at the API Manager layer, completely decoupled from your Mule application code.

Policy-layer enforcement
Monetization runs in the Mule runtime policy chain — before your flow logic executes
Zero .jar modifications
No changes to Mule applications, DataWeave transformations, or connector configs
Anypoint Exchange native
Publish once to Exchange. Apply to any API via API Manager — same as any MuleSoft policy
Runtime Fabric compatible
Works on CloudHub 2.0, Runtime Fabric, and Hybrid deployments
INFO
This is the key difference from competing billing tools. Most require you to add SDK calls inside your Mule flows. Aforo sits outside the flow at the policy layer — the same layer where you apply rate limiting and OAuth validation today.

Prerequisites#

REQUIRED
Anypoint Platform account
Organization Admin or Exchange Contributor role
REQUIRED
API Manager access
Environment-level permissions to apply policies to managed APIs
REQUIRED
Aforo API Key
sk_live_* key from Workspace Admin → API Keys
REQUIRED
Mule Runtime 4.3+
Custom policies require Mule 4.x runtime (CloudHub 2.0 or Runtime Fabric)
OPTIONAL
Maven (optional)
Only needed if building the policy from source instead of importing the pre-built asset

Step 1: Get the Policy & Publish to Anypoint Exchange#

The MuleSoft policy lives in the Aforo SDK distribution repo at aforo-gateway-plugins/mulesoft/. These are Anypoint policy descriptor YAML files — not a registry package — so clone the repo and publish each descriptor to your organization's Exchange:

terminal
# Clone the SDK distribution repo and enter the MuleSoft policy folder
git clone https://github.com/aforoai/SDKs.git
cd SDKs/aforo-gateway-plugins/mulesoft

# Policy descriptors in this folder:
#   jwt-validation-config.yaml    -> id: aforo-jwt-validation   (apply FIRST on every API)
#   mule-policy.yaml              -> id: aforo-metering          (standard + MCP)
#   mcp-mule-policy.yaml          -> id: aforo-mcp-metering      (MCP-only alternative)
#   margin-guard-policy.yaml      -> id: aforo-margin-guard      (optional)
#   preflight-quota-policy.yaml   -> id: aforo-preflight-quota   (optional)
#   compound-metering-policy.yaml -> id: aforo-compound-metering (optional)
WARNING
Policy ordering is a security boundary that Anypoint enforces. Apply aforo-jwt-validation first — every metering / margin-guard / quota policy declares requiredCharacteristics: [aforo-jwt-validated], so Anypoint refuses to attach a metering policy to an API without JWT validation. customerId/tenantId always come from the verified JWT (vars.aforo.customerId / vars.aforo.tenantId), never from a request header.

Publish via the Anypoint UI

Publish each descriptor to Exchange:

1Navigate to Anypoint Platform → Exchange → Publish new asset
2Select asset type: "Custom Policy"
3Upload the policy descriptor YAML (start with jwt-validation-config.yaml, then mule-policy.yaml)
4jwt-validation-config.yaml also needs the Mule JWT Module (com.mulesoft.modules:mule-jwt-module, classifier mule-plugin) and the inline Mule flow XML from that file’s comment block in your gateway project
5Click "Publish" — the policy is now available to all environments

Step 2: Apply via API Manager#

Once the policy is in Exchange, apply it to your managed APIs through API Manager:

1Open Anypoint Platform → API Manager → select your target API
2Click "Policies" tab → "Add Policy"
3Search for "aforo-metering" in the policy catalog
4Select the policy and click "Configure"
5Fill in the required parameters (see Step 3 below)
6Click "Apply" — the policy activates immediately on the next request
PRO TIP
To apply globally across all APIs in an environment, use the Automated Policy feature: API Manager → Automated Policies → Add → select aforo-metering. This mirrors the Kong "global plugin" and Apigee "Flow Hook" patterns.

Step 3: Configuration Parameters#

The policy requires the following configuration when applied:

aforo-policy-config.yaml
# The aforo-metering policy takes exactly five parameters
aforo-endpoint: "https://ingest.aforo.ai/v1/ingest/batch"   # ingest batch URL
aforo-api-key: "sk_live_your_key_here"                       # Aforo API key
aforo-tenant-id: "your-workspace-id"                         # static workspace id
mcp-enabled: false                                           # set true for MCP servers
mcp-product-id: ""                                           # required when mcp-enabled: true
INFO
Customer and tenant identity are resolved from the verified JWT claim, not from a request header. Margin-guard enforcement is a separate policy (aforo-margin-guard) you apply alongside this one — it isn't a parameter of the metering policy.
ParameterDescriptionRequired
aforo-endpointMetering ingestion batch URLYES
aforo-api-keyYour Aforo API key (sk_live_*)YES
aforo-tenant-idYour workspace (tenant) idYES
mcp-enabledDetect MCP tools/call requests (default: false)NO
mcp-product-idAforo product id — required when mcp-enabled is trueNO

The Zero-Touch Benefit#

Once the Aforo policy is applied, no changes are required to any underlying Mule application:

UNTOUCHED
Your .jar files
Mule applications run exactly as before
UNTOUCHED
Your DataWeave
Transformations, connectors, error handlers — unchanged
UNTOUCHED
Your CI/CD
Build pipelines, deployment scripts — no modifications
<5ms
MuleSoft Policy Decision
Entitlement + margin check in Mule runtime policy chain. Same performance as native rate limiting.
INFO
Monetization happens entirely at the policy layer. The Mule runtime executes the Aforo policy in the request/response chain — the same place where you run OAuth, rate limiting, and IP whitelisting today. Your application code never knows Aforo exists.
POLICY EXECUTION ORDER
1. OAuth 2.0 Validation → Identity verified
2. Rate Limiting → Burst protection
3. Aforo Entitlement Check → Subscription + quota + margin verified
4. Your Mule Flow → Application logic executes
5. Aforo Async Metering → Usage event captured (post-response)

Verification#

Verify the policy is active and correctly routing events:

terminal
# Check policy status via Anypoint CLI
anypoint-cli api-mgr policy list \
  --environment prod \
  --apiInstanceId {API_ID}

# Expected output:
# ID    | Policy          | Status
# 12345 | aforo-metering  | ACTIVE

# Send a test request through the API
curl -v https://your-api.cloudhub.io/api/endpoint \
  -H "X-Tenant-Id: test_tenant_123" \
  -H "Authorization: Bearer customer_token"

# Check for Aforo response headers:
# X-Aforo-Remaining: 8420
# X-Aforo-Plan: enterprise
# X-Aforo-Margin-Status: healthy

# Verify event arrived in Aforo
curl -s "https://api.aforo.ai/v1/events?tenant_id=test_tenant_123&limit=1" \
  -H "Authorization: Bearer sk_live_your_admin_key" | jq .
PRO TIP
If events are not appearing, check the Anypoint Runtime Manager logs. Look for [aforo-policy] log entries. Common issues: incorrect environment_id mapping, expired API key, or outbound HTTPS blocked by the VPC firewall (allow ingest.aforo.ai:443).