MuleSoft Integration (Custom Policy)

Task Overview#

What the policy does#

aforo-metering is a Mule 4 custom policy. You apply it in API Manager like rate limiting or JWT validation; your Mule applications are not rebuilt or redeployed. After each response it builds one usage event and posts it to Aforo from an async scope, so the API call is not delayed and is never failed by the policy.

The event is built once and sent up to three times, one second apart, on a transport error, a 5xx or a 429. Every attempt carries the same idempotencyKey, so a redelivery is deduplicated instead of billed twice.

Prerequisites#

Install from Aforo (one click)#

Use this when the MuleSoft connection in Aforo already points at the organization and environment that host your APIs.

Deploy does three things in your Anypoint organization:

Install yourself: publish to Exchange#

A custom policy is two files in Exchange: a jar and a definition YAML. API Manager cannot use a YAML uploaded on its own, so the policy ships as a Maven project that builds and publishes both.

git clone https://github.com/aforoai/SDKs.git
cd SDKs/aforo-gateway-plugins/mulesoft/aforo-metering

# Build only (writes target/aforo-metering-1.0.0-mule-policy.jar)
mvn clean package

Add your Exchange credentials to ~/.m2/settings.xml. For a connected app, the username is the literal ~~~Client~~~ and the password is the client id and secret joined by ~?~:

<servers>
  <server>
    <id>exchange-server</id>
    <username>~~~Client~~~</username>
    <password>CLIENT_ID~?~CLIENT_SECRET</password>
  </server>
</servers>

Publish. Exchange only accepts an asset whose group id is your organization id (Access Management → Organization), so pass it:

mvn clean deploy -Danypoint.org.id=YOUR_ORG_ID

Install yourself: apply in API Manager#

To script it, send the same thing to the API Manager API:

curl -X POST \
  "https://anypoint.mulesoft.com/apimanager/api/v1/organizations/$ORG_ID/environments/$ENV_ID/apis/$API_INSTANCE_ID/policies" \
  -H "Authorization: Bearer $ANYPOINT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "'"$ORG_ID"'",
    "assetId": "aforo-metering",
    "assetVersion": "1.0.0",
    "pointcutData": null,
    "configurationData": {
      "aforo-endpoint": "https://api.aforo.ai/v1/ingest/batch",
      "aforo-api-key": "sk_live_your_key_here",
      "aforo-tenant-id": "your-workspace-id"
    }
  }'

Configuration#

Where the customer id comes from#

The policy reads the customer id from the claims that MuleSoft’s JWT Validation policy has verified: the customer-id-claim claim, then sub. It reads no request header for identity, so a caller cannot bill another customer by sending X-Client-Id or X-Customer-Id.

How Calls Get an Outcome#

Read this if any rate plan behind this gateway uses Outcome-Based pricing — it bills each call at a weight for its executionStatus. Every other pricing model ignores the field. The plugin sets it from the upstream response status:

Override the status for specific codes

When the default table is wrong for your API — say a 404 is a normal answer, not a failure — map exact codes with the optional status-outcomes policy parameter. Format: comma-separated code=STATUS pairs:

status-outcomes: "404=SUCCESS,429=ERROR"

Keys are exact HTTP codes from 200 to 599. Values must be one of the 11 statuses: SUCCESS, PARTIAL, TIMEOUT, ERROR, VALIDATION_FAILED, FAILED, FAILURE, CANCELLED, PENDING, BLOCKED, HITL_REQUIRED. Invalid entries are ignored without a warning. If a code is listed twice, the last valid entry wins. An override can't give a status to a missing, 0 or 1xx code.

Requests that aren't metered

By default, responses with status 401, 403 or 429 and requests to /health, /ready or /metrics produce no event at all — they cost nothing whatever the rate plan says. All five gateway plugins share this default. A path is skipped when it equals an entry or starts with it, so /health also covers /health/live.

Leave a parameter empty to get its default. Entries that aren't whole numbers from 100 to 599 are ignored. A list you set replaces the default rather than adding to it: a status list of 404,500 skips only those two and starts metering 401, 403 and 429. A status you choose to meter bills as BLOCKED unless you override it above.

# also skip 404s and everything under /internal
exclude-status-codes: "401,403,429,404"
exclude-paths: "/health,/ready,/metrics,/internal"

What is not covered#

Verification#

# Applied policies on the instance: look for assetId "aforo-metering"
curl -s \
  "https://anypoint.mulesoft.com/apimanager/api/v1/organizations/$ORG_ID/environments/$ENV_ID/apis/$API_INSTANCE_ID/policies" \
  -H "Authorization: Bearer $ANYPOINT_TOKEN"

# One metered call
curl -s "https://your-api.example.com/v1/orders" -H "Authorization: Bearer $CUSTOMER_JWT"

Troubleshooting#