APIM Policy Authoring Skill

Generates production-ready Azure API Management policy XML with authentication, rate limiting, CORS, error handling, correlation IDs, and security headers.

When to Use This Skill

Activate this skill when users need:

• Authentication policies: OAuth 2.0, JWT validation, hybrid auth with subscription keys

• Rate limiting: Per-user or per-subscription throttling

• CORS configuration: Cross-origin access for browser-based clients

• Error handling: Standardized error responses with correlation IDs

• Request/response transformation: Header manipulation, body transformations

• Security headers: X-Content-Type-Options, X-Frame-Options, etc.

Policy Templates

See references/POLICY_TEMPLATES.md for complete production-ready XML templates:

• Hybrid Authentication - OAuth + subscription key fallback for public APIs

• OAuth Only - Internal corporate APIs with Entra ID

• Subscription Key Only - Simple public read-only APIs

Policy Execution Flow

INBOUND → BACKEND → OUTBOUND → ON-ERROR

1. INBOUND: Authentication, rate limiting, CORS, headers
2. BACKEND: Forwarding, retry, circuit breaker
3. OUTBOUND: Response transform, security headers, cleanup
4. ON-ERROR: Structured errors, logging, correlation ID

Important: MCP Tools (ALWAYS Use Before Writing Policies)

1. Call Best Practices FIRST

Before ANY policy generation, call:

Tool: mcp_azure_mcp_get_azure_bestpractices Intent: "Azure API Management policy best practices for [authentication|rate-limiting|CORS|error-handling]"

2. Search Documentation

For specific policy elements:

Tool: mcp_azure_mcp_documentation search Query: "APIM validate-jwt policy reference"

1. JWT Validation with Entra ID

<validate-jwt header-name="Authorization"> <openid-config url="https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration" /> <audiences> <audience>api://{client-id}</audience> </audiences> </validate-jwt>

2. Per-User Rate Limiting

<set-variable name="userId" value="@(context.Request.Headers.GetValueOrDefault('Authorization','').AsJwt()?.Subject)" /> <rate-limit-by-key calls="1000" renewal-period="3600" counter-key="@((string)context.Variables['userId'])" />

3. Correlation ID Generation

<set-variable name="correlationId" value="@(Guid.NewGuid().ToString())" /> <set-header name="X-Correlation-ID" exists-action="override"> <value>@((string)context.Variables["correlationId"])</value> </set-header>

4. Standardized Error Response

<on-error> <set-body>@{ return new JObject( new JProperty("error", new JObject( new JProperty("code", context.LastError.Source), new JProperty("message", context.LastError.Message), new JProperty("correlationId", context.Variables["correlationId"]), new JProperty("timestamp", DateTime.UtcNow.ToString("o")) )) ).ToString(); }</set-body> </on-error>

5. Security Headers

<set-header name="X-Content-Type-Options" exists-action="override"> <value>nosniff</value> </set-header> <set-header name="X-Frame-Options" exists-action="override"> <value>DENY</value> </set-header> <set-header name="Strict-Transport-Security" exists-action="override"> <value>max-age=31536000; includeSubDomains</value> </set-header>

Authentication Decision Matrix

API Type Authentication Rate Limit Use Case

Public Read-Only Subscription Keys 500 req/hour Weather API, Public Holidays

Internal Corporate OAuth (Entra ID) 10,000 req/hour Employee Directory, HR Systems

Sensitive Public OAuth (Entra External ID) 1,000 req/hour Payment, Health Records

Hybrid OAuth + Keys Fallback 1,000/500 req/hour APIs with free/premium tiers

Policy Validation Checklist

Before deploying, verify:

• Correlation ID: Generated in <inbound> , included in response + error

• Authentication: JWT validation or subscription key check

• Rate limiting: Configured with appropriate limits

• Error handling: <on-error> block with structured JSON

• Security headers: X-Content-Type-Options, X-Frame-Options, HSTS

• Backend cleanup: Remove X-Powered-By , Server in <outbound>

• XML validity: Well-formed, no unclosed tags

• Testing: Valid/invalid tokens, rate limit exceeded

Related Skills

• azure-apim-architecture - Understand architecture before policy authoring

• api-security-review - Validate security after policy creation

Microsoft Documentation

• Policy Reference

• validate-jwt

• rate-limit-by-key

• CORS

• Policy Expressions

Skill Version: 1.0

Last Updated: 29 January 2026

Primary Knowledge: APIM_PLATFORM_BASELINE_POLICIES.md, references/POLICY_TEMPLATES.md