Gateways1 min read

MuleSoft Integration (Custom Policy)

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

Docs  Gateways  MuleSoft

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 Admin Panel → Settings → 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: Download & Upload to Anypoint Exchange#

Download the pre-built Aforo Custom Policy asset and publish it to your organization's Anypoint Exchange:

terminal

# Download the Aforo Custom Policy asset
curl -LO https://github.com/aforoai/mulesoft-policy-aforo-metering/releases/latest/download/aforo-monetization-policy.jar

# Publish to your Anypoint Exchange via Maven
mvn deploy:deploy-file \
  -DgroupId=com.aforo.policy \
  -DartifactId=aforo-monetization-policy \
  -Dversion=1.0.0 \
  -Dpackaging=jar \
  -Dfile=aforo-monetization-policy.jar \
  -DrepositoryId=anypoint-exchange-v3 \
  -Durl=https://maven.anypoint.mulesoft.com/api/v3/organizations/{ORG_ID}/maven

Alternative: Upload via Anypoint UI

If you prefer the UI:

1Navigate to Anypoint Platform → Exchange → Publish new asset

2Select asset type: "Custom Policy"

3Upload the aforo-monetization-policy.jar file

4Set Group ID: com.aforo.policy, Asset ID: aforo-monetization-policy

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 Monetization" 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 Monetization. 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

# Required parameters
aforo_api_key: "sk_live_your_key_here"
aforo_ingest_url: "https://ingest.aforo.ai/v1/ingest"
environment_id: "prod"               # maps to your Aforo environment
tenant_id_header: "X-Tenant-Id"      # header containing the tenant identifier

# Optional tuning
batch_size: 100                       # events per batch flush
flush_interval_ms: 5000               # flush every 5 seconds
entitlement_cache_ttl: 30             # Redis cache TTL in seconds
margin_guard_enabled: true            # enable L1-L3 enforcement
margin_guard_block_threshold: 0       # margin % below which L3 blocks

ParameterDescriptionRequired

aforo_api_keyYour Aforo admin API key (sk_live_*)YES

aforo_ingest_urlMetering ingestion endpointYES

environment_idAforo environment identifier (prod, staging)YES

tenant_id_headerHTTP header containing tenant IDYES

batch_sizeEvents per batch flush (default: 100)NO

margin_guard_enabledEnable margin protection (default: true)NO

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

OAuth 2.0 Validation → Identity verified
Rate Limiting → Burst protection
Aforo Entitlement Check → Subscription + quota + margin verified
Your Mule Flow → Application logic executes
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 Monetization      | ACTIVE

# PaperPlaneTilt 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).