MuleSoft Applying API Policies
API policies are rules that the API Gateway enforces on every request before it reaches your Mule application. You apply policies in API Manager without touching your application code. Changes take effect instantly on live traffic. MuleSoft includes over 20 built-in policies, and you can build custom ones.
How Policies Work
The API Gateway intercepts every incoming request. It evaluates applied policies in order — if a request fails any policy, the gateway rejects it and returns an error response. Only requests that pass all policies reach your Mule application.
Policy Enforcement Pipeline
Incoming Request
│
▼
[Policy 1: TLS Check]
Pass? ─► [Policy 2: IP Allowlist]
Pass? ─► [Policy 3: Client ID Enforcement]
Pass? ─► [Policy 4: Rate Limiting]
Pass? ─► [Mule Application]
Fail? ─► 429 Too Many Requests
Fail? ─► 401 Unauthorized
Fail? ─► 403 Forbidden (IP not allowed)
Fail? ─► 400 Bad Request (no TLS)
Applying a Policy in API Manager
- Open API Manager and select your API instance
- Click Policies in the left navigation
- Click Apply New Policy
- Browse or search for the policy (e.g., "Rate Limiting")
- Click the policy name to see its description
- Click Configure Policy
- Fill in the configuration fields
- Click Apply
The policy starts enforcing immediately — no redeployment required.
Security Policies
Client ID Enforcement
Config: Client ID Expression: #[attributes.headers.'client_id'] Client Secret Expression: #[attributes.headers.'client_secret'] Behavior: Validates client_id and client_secret against Anypoint Platform registry. Valid pair → request continues. Invalid or missing → 401 Unauthorized.
OAuth 2.0 Access Token Enforcement
Config: Token Validation Endpoint: https://auth.mycompany.com/oauth/introspect Scopes Validation Type: ANY (any listed scope grants access) Required Scopes: read:orders, write:orders Behavior: Validates Bearer token from Authorization header. Expired token → 401 Unauthorized. Wrong scope → 403 Forbidden. Valid token → request continues.
JWT Validation Policy
Config:
JWT Origin: Authorization Header
JWT Expression: #[attributes.headers.Authorization[7 to -1]]
Signing Method: RSA
JWK URL: https://auth.mycompany.com/.well-known/jwks.json
Validate Claims:
Issuer: auth.mycompany.com
Audience: orders-api
Clock Skew: 10 seconds
Behavior:
Decodes and validates JWT signature using the public key from JWK URL.
Validates all configured claims.
Invalid → 401 Unauthorized.
Traffic Management Policies
Rate Limiting Policy
Config:
Limits:
- Maximum Requests: 100
Time Period: 1
Time Unit: MINUTE
Identifier: #[attributes.headers.'client_id'] (limit per client)
Behavior:
Counts requests per client per minute.
Request 101 in the same minute → 429 Too Many Requests.
Response Header: X-RateLimit-Remaining, X-RateLimit-Limit, X-RateLimit-Reset.
Throttling Policy
Throttling is similar to rate limiting but queues excess requests instead of immediately rejecting them. Requests that arrive over the limit wait in a queue and process when capacity is available. This is gentler on clients that occasionally burst over the limit.
Config: Maximum Requests Per Period: 100 Time Period: 1 MINUTE Queuing Timeout: 2000 ms (wait up to 2 seconds before rejecting) Behavior: Request 101 → queued for up to 2 seconds If capacity opens: request processes normally If 2 seconds pass: 429 Too Many Requests
Spike Control Policy
Spike Control prevents sudden traffic bursts from overwhelming the API. It limits how many requests can be processed per time window, smoothing out traffic spikes.
Data Quality Policies
JSON Threat Protection
Config: Max Container Depth: 10 Max String Value Length: 5000 Max Object Entry Count: 50 Max Array Element Count: 100 Max Object Entry Name Length: 256 Behavior: Rejects payloads exceeding any limit with 400 Bad Request. Prevents deeply nested JSON attacks that could exhaust processing resources.
XML Threat Protection
Config: Max Node Depth: 10 Max Attribute Count: 30 Max Child Count: 50 Max Text Length: 10000 Behavior: Rejects XML with structures that could trigger XML parsing vulnerabilities (Billion Laughs attack, etc.).
Schema Validation Policy
Validates the request body against a JSON Schema or XML Schema. Requests with invalid structure are rejected before reaching the application.
Transformation Policies
HTTP Caching Policy
Caches GET request responses for a configurable time period. When the same request arrives again within the cache window, API Manager returns the cached response without calling the Mule application. This dramatically reduces response times and backend load for read-heavy APIs.
Config: Request Expression: #[attributes.requestPath ++ "?" ++ attributes.rawQueryString] TTL (seconds): 300 (cache responses for 5 minutes) Cacheable Methods: GET, HEAD Behavior: Request 1: GET /products → Mule app processes → response cached Request 2: GET /products → served from cache in <1ms (no app call) After 300s: cache expires → next request goes to Mule app again
Policy Order and Priority
When multiple policies apply to the same API, order matters. Security policies should run before traffic management. Traffic management should run before transformation. MuleSoft assigns default policy order by category, but you can drag and reorder policies in the API Manager Policies tab.
Recommended Policy Order
Order 1: TLS Enforcement (reject non-HTTPS first) Order 2: IP Allowlist/Blocklist (reject bad IPs) Order 3: Client ID / OAuth / JWT (authentication) Order 4: Rate Limiting or Throttling (traffic control) Order 5: JSON/XML Threat Protection (payload validation) Order 6: HTTP Caching (performance)
Removing a Policy
Remove a policy by clicking the three-dot menu next to it in the Policies tab and selecting Remove. The change takes effect immediately. Use this ability carefully in production — removing a security policy exposes your API to unauthenticated access instantly.