Migrating from Azure API Management to Zuplo: Policy Mapping, Architecture Translation, and Step-by-Step Guide

Azure API Management is a natural choice for teams already invested in the Microsoft Azure ecosystem. But as API programs grow, the operational overhead of managing APIM instances, navigating XML-based policy expressions, and dealing with complex tier-based pricing becomes a real burden. If your team is evaluating a move to a modern, edge-native API gateway, this guide walks you through every step of migrating from Azure API Management to Zuplo.

What This Guide Covers

Why Migrate from Azure API Management?
Architecture Comparison
Policy Mapping Reference
Translating Azure APIM Configuration to Zuplo
Authentication Migration
Developer Portal Migration
Step-by-Step Migration Playbook
Post-Migration Benefits
Frequently Asked Questions
Next Steps

Why Migrate from Azure API Management?

Azure APIM is a capable platform, but several pain points drive teams to explore alternatives:

Complex, tier-based pricing — Azure APIM’s pricing model spans Developer (~~$30/month), Basic v2 (~~$150/month), Standard v2 (~~$700/month), and Premium v2 (~~$2,800/month) tiers. Each environment (dev, staging, production) requires its own instance, and production workloads often need the Standard or Premium tier for features like VNET integration. Costs escalate quickly in multi-environment setups.
Slow deployment cycles — Azure APIM deployments can take 15–45 minutes to propagate. Creating a new APIM instance can take 30–60 minutes. This creates painful feedback loops during development and testing.
XML policy complexity — Azure APIM policies are written in XML with inline C# expressions. The syntax is verbose, error-prone, and difficult to test or debug outside the Azure portal. Version control is awkward because XML policy definitions don’t merge cleanly in Git.
Azure lock-in — APIM is tightly integrated with the Azure ecosystem. Using it with non-Azure backends or in multi-cloud architectures adds friction — VNET peering, private endpoints, and Azure AD integration all assume you’re running on Azure.
Limited GitOps support — While Azure APIM supports ARM templates, Bicep, and Terraform for infrastructure-as-code, the policy definitions remain embedded XML that doesn’t fit naturally into a Git-based development workflow. There’s no native “push to Git, deploy to gateway” experience.
Regional deployment model — Azure APIM instances are deployed to specific Azure regions. Multi-region deployment requires the Premium tier and manual configuration. There’s no built-in global edge distribution.

Architecture Comparison

Understanding the architectural differences helps you plan a clean migration.

Azure APIM’s Architecture

Azure API Management uses a gateway + management plane model. A typical setup involves:

An APIM instance deployed to one or more Azure regions
API definitions stored as OpenAPI specs with XML policy overlays
Products that bundle APIs with subscription keys and usage quotas
Policies written in XML with C# expressions, applied at global, product, API, or operation scope
A developer portal deployed alongside the APIM instance
VNET integration (Standard or Premium tier) for private backend connectivity
ARM templates or Bicep for infrastructure-as-code deployment

Zuplo’s Architecture

Zuplo takes a fundamentally different approach:

Edge-native deployment — Your gateway runs across 300+ data centers worldwide automatically. There’s no single-region deployment to manage or scale.
OpenAPI-native routing — Routes are defined in a standard routes.oas.json file using the OpenAPI specification format, extended with x-zuplo-route for gateway behavior.
TypeScript policies — Instead of XML with C# expressions, you write policies in TypeScript with full IDE support, type safety, and access to npm packages.
Git-native CI/CD — Every configuration change is version-controlled. Push to GitHub, and your gateway deploys to the edge automatically. Every branch gets its own isolated preview environment.
Fully managed — No instances to provision, no VNET complexity, no capacity planning. Zuplo handles all infrastructure, scaling, and updates.
Built-in developer portal — Auto-generated from your OpenAPI spec, with API key management and an API explorer included.

Policy Mapping Reference

One of the biggest questions during migration is: “What replaces my Azure APIM policies?” Below is a mapping of Azure APIM’s most common policies to their Zuplo equivalents.

Authentication and Authorization

validate-jwt → JWT Auth Policy (OpenID) — Validates JWT tokens from any OpenID-compliant provider, including Microsoft Entra ID, Auth0, Okta, and others. Zuplo also has provider-specific JWT policies for Auth0, Cognito, Clerk, Supabase, Firebase, and more.
authentication-basic → Basic Auth Policy — Built-in support for HTTP Basic authentication.
Subscription keys → API Key Authentication — Zuplo’s managed API key service replaces Azure APIM subscription keys with globally distributed validation, self-serve key management through the developer portal, and consumer metadata.

Traffic Control

rate-limit / rate-limit-by-key → Rate Limiting Policy — Supports per-user, per-IP, per-API-key, or custom attribute-based rate limits. Unlike Azure APIM’s regional rate limiting, Zuplo’s rate limiter is globally distributed across all edge locations. No Redis or separate infrastructure required.
quota / quota-by-key → Quota Policy — Enforces long-term usage quotas per consumer.
ip-filter → IP Restriction Policy — Allow/deny lists with CIDR range support. For advanced scenarios, write custom IP filtering logic using a Custom Code Policy.
cors → Built-in CORS Configuration — Configure allowed origins, methods, and headers per route. Supports wildcard subdomains and environment variables.

Request and Response Transformation

set-header → Set Headers Policy — Add or overwrite request headers before forwarding to your backend.
remove-header → Remove Headers Policy — Strip headers from requests or responses.
set-body → Set Body Policy — Replace the request or response body.
set-query-parameter → Set Query Params Policy — Add or modify query parameters.
rewrite-uri → URL Rewrite Handler — Rewrite incoming request URLs using template interpolation with access to path parameters, query strings, headers, and environment variables.
find-and-replace → Replace String Policy — Find and replace content in response bodies.
xml-to-json / json-to-xml → XML to JSON Policy — Convert between XML and JSON formats, especially useful for modernizing legacy SOAP backends.

Security and Validation

check-header → Custom Code Policy — Write a TypeScript function to validate any header, returning an error response if the check fails.
validate-content → Request Validation Policy — Validates request bodies, query parameters, path parameters, and headers against your OpenAPI schema definitions automatically.

Caching and Performance

cache-lookup / cache-store → Zuplo supports caching policies for response caching at the edge.

Custom Logic

C# policy expressions → Custom Code Policy — Any inline C# expression or complex policy logic translates to a TypeScript function. You get full IDE support, type safety, npm package access, and standard Web APIs (Request, Response, Headers, fetch).

Translating Azure APIM Configuration to Zuplo

XML Policies → JSON + TypeScript

In Azure APIM, policies are XML documents with inline C# expressions:

xml

<policies>
  <inbound>
    <rate-limit-by-key
      calls="100"
      renewal-period="60"
      counter-key="@(context.Subscription.Id)" />
    <set-header name="X-Request-Id" exists-action="skip">
      <value>@(Guid.NewGuid().ToString())</value>
    </set-header>
  </inbound>
</policies>

In Zuplo, the equivalent is declarative JSON policies in policies.json:

json

{
  "policies": [
    {
      "name": "rate-limit",
      "policyType": "rate-limit-inbound",
      "handler": {
        "export": "RateLimitInboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "rateLimitBy": "user",
          "requestsAllowed": 100,
          "timeWindowMinutes": 1
        }
      }
    }
  ]
}

Key differences to note:

JSON instead of XML — Zuplo policies are standard JSON, which merges cleanly in Git and is easy to lint and validate.
TypeScript instead of C# — Custom logic is written in TypeScript with full IDE support, not embedded as inline expressions in XML attributes.
Everything in Git — Both routes.oas.json and policies.json are files in your repository. There’s no separate management plane or portal state to keep in sync.

Azure APIM C# Expressions → Zuplo TypeScript

Azure APIM’s inline C# expressions handle complex logic like conditional routing, header manipulation, and error handling. In Zuplo, these become clean TypeScript functions:

Azure APIM (XML + C#):

xml

<policies>
  <inbound>
    <choose>
      <when condition="@(context.Request.Headers
        .GetValueOrDefault("Authorization","")
        .Length == 0)">
        <return-response>
          <set-status code="401" reason="Unauthorized" />
          <set-body>{"error": "Missing authorization"}</set-body>
        </return-response>
      </when>
    </choose>
  </inbound>
</policies>

Zuplo (TypeScript):

typescript

import { ZuploContext, ZuploRequest, HttpProblems } from "@zuplo/runtime";

export default async function (
  request: ZuploRequest,
  context: ZuploContext,
  options: never,
  policyName: string,
) {
  const authHeader = request.headers.get("authorization");

  if (!authHeader) {
    return HttpProblems.unauthorized(request, context, {
      detail: "Missing authorization",
    });
  }

  return request;
}

The TypeScript version is easier to read, easier to test, and provides full type checking in your IDE.

Named Values → Environment Variables

Azure APIM’s named values (plain, secret, and Key Vault references) map directly to Zuplo environment variables:

Plain named values → Standard environment variables, referenced as $env(VARIABLE_NAME) in route configuration or environment.VARIABLE_NAME in TypeScript code.
Secret named values and Key Vault references → Secret environment variables in Zuplo, which are encrypted at rest and never exposed in logs or the UI after creation.

Concept Mapping Reference

Here is a quick reference for how Azure APIM concepts translate to Zuplo:

API → Routes in your OpenAPI spec (routes.oas.json)
Operation → Route (path + method) in your OpenAPI spec
Backend → URL Forward or URL Rewrite handler target
Inbound policy (XML) → Inbound policy (TypeScript/JSON)
Outbound policy (XML) → Outbound policy (TypeScript/JSON)
Named value → Environment variable
Subscription key → API key authentication
Product → API key with consumer metadata
APIM instance → Zuplo environment (automatically provisioned)
Developer portal → Zuplo Developer Portal (auto-generated from your OpenAPI spec)
Application Insights → Logging integrations (Datadog, Splunk, OpenTelemetry, and others)
API revision → Git branch with branch-based deployment
Self-hosted gateway → Self-hosted Zuplo

Authentication Migration

Authentication is typically the most critical part of any gateway migration. Here’s how to approach each Azure APIM authentication mechanism.

Azure AD (Entra ID) JWT Validation

If you’re using Azure APIM’s validate-jwt policy with Microsoft Entra ID (formerly Azure AD), migration is straightforward. Configure Zuplo’s JWT Auth Policy with your Entra ID tenant details:

json

{
  "name": "entra-id-auth",
  "policyType": "open-id-jwt-auth-inbound",
  "handler": {
    "export": "OpenIdJwtInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
      "audience": "api://your-app-id",
      "jwkUrl": "https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys"
    }
  }
}

Zuplo validates the JWT signature, expiration, issuer, and audience at the edge. The authenticated user’s claims are available in your policies and handlers via request.user.

Subscription Keys → Zuplo API Keys

Azure APIM subscription keys are tied to products and require manual management through the Azure portal or ARM templates. Zuplo’s API Key Authentication policy provides a more developer-friendly approach:

Add the api-key-inbound policy to your routes
Create consumers with metadata (plan tier, organization, rate limit overrides) through the Zuplo Portal or Developer API
Optionally enable the Developer Portal for self-serve key management

To migrate existing subscription keys, use Zuplo’s Developer API to programmatically create consumers and import keys, so existing client integrations continue working without changes.

OAuth 2.0 Flows

If Azure APIM is validating OAuth 2.0 bearer tokens from any identity provider, Zuplo’s JWT policies handle this directly. Your identity provider (Entra ID, Auth0, Okta, etc.) continues to issue tokens — Zuplo validates them at the edge. Provider-specific policies are available for Auth0, AWS Cognito, Clerk, Supabase, Firebase, and Okta.

Developer Portal Migration

Azure APIM’s built-in developer portal requires significant effort to customize and maintain. It runs as a separate application alongside your APIM instance, requires manual content management, and doesn’t automatically stay in sync with your API definitions.

Zuplo’s developer portal is auto-generated from your OpenAPI spec. When you update your routes in routes.oas.json, the portal updates automatically. Features include:

Automatic API documentation — generated directly from your OpenAPI specification, always in sync
API Explorer — developers can test your API directly from the docs
Self-serve API key management — consumers sign up, create keys, and manage them without admin intervention
Custom branding and pages — add custom documentation pages with MDX (Markdown + JSX components)
Custom domains — host your portal on docs.yourcompany.com

Migration Steps

Export your OpenAPI specs from Azure APIM — use the Azure portal (APIs → Export → OpenAPI v3) or the Azure CLI
Import into Zuplo — your specs become both your gateway configuration and your portal documentation
Add custom pages — migrate any guides or tutorials from your Azure APIM portal to MDX custom pages
Configure developer sign-in — set up authentication using your identity provider
Update DNS — point your developer portal domain to Zuplo

The biggest win is eliminating the separate portal management overhead. No more manually syncing documentation with your actual API behavior.

Step-by-Step Migration Playbook

A typical Azure APIM-to-Zuplo migration follows four phases.

Phase 1: Audit and Setup (Week 1)

Inventory your Azure APIM setup:

List every API and its operations (routes)
Document all policies at each scope (global, product, API, operation)
Catalog named values and their types (plain, secret, Key Vault)
Export OpenAPI specs for all APIs
List all products, subscriptions, and their configurations
Note any custom C# policy expressions

Set up Zuplo:

Create a Zuplo account at portal.zuplo.com
Connect your GitHub repository
Import your OpenAPI specs to bootstrap route configuration
Configure authentication policies to match your Azure APIM auth setup
Set up rate limiting and quota policies
Add environment variables for backend URLs and secrets

Phase 2: Policy Translation and Testing (Week 2)

Translate XML policies to Zuplo JSON policies using the mapping reference above
Rewrite C# policy expressions as TypeScript custom code policies
Configure the developer portal
Test all routes against your backend services
Validate authentication flows end-to-end
Run load tests to verify rate limiting behavior
Review logging and observability configuration

Phase 3: Parallel Running and Cutover (Week 3)

Run Zuplo alongside Azure APIM to validate behavior:

Deploy your Zuplo project by pushing to your Git repository
Set up a custom domain for your Zuplo gateway
Route a subset of traffic to Zuplo using DNS-based routing or Azure Front Door
Compare response behavior between Azure APIM and Zuplo
Gradually increase traffic to Zuplo as you validate correctness
Complete the full cutover once you’re confident

DNS-based blue-green cutover:

Lower your API domain’s DNS TTL to 60 seconds (24 hours before cutover)
Switch the DNS record to point at Zuplo’s edge network
Monitor error rates and latency
Roll back by reverting DNS if anything goes wrong

Phase 4: Validation and Cleanup (Week 4)

After full cutover:

Verify all routes return expected response codes
Confirm authentication works for all methods (JWT, API keys)
Validate rate limiting triggers at correct thresholds
Check that logs flow to your monitoring system
Update developer portal URLs and API documentation
Decommission Azure APIM instances

Rollback Strategy

Because Zuplo deployments are Git-based, rollback is straightforward:

Configuration rollback — Revert the Git commit and push. The previous gateway configuration deploys automatically.
DNS rollback — If you kept Azure APIM running during the parallel phase, switch DNS back to your APIM endpoints.

Post-Migration Benefits

Once you’ve completed the migration, you’ll immediately benefit from capabilities that Azure APIM doesn’t offer:

Global Edge Performance

Your APIs now run at 300+ edge locations worldwide. Requests are automatically routed to the nearest point of presence, reducing latency for users everywhere — not just in the Azure regions where APIM was deployed. There’s no Premium tier upgrade needed for multi-region, no VNET configuration, and no capacity planning.

GitOps-Native Workflow

Every change to your API gateway is a Git commit. Open a pull request and get an isolated preview environment automatically. Review policy changes in code review, just like application code. Roll back by reverting a commit. If you’re new to this approach, see our overview of what GitOps is and why it matters. This is a fundamentally better workflow than managing ARM templates, Bicep files, and XML policy documents through Azure DevOps pipelines.

TypeScript Programmability

Custom gateway logic is standard TypeScript — not XML with embedded C# expressions. You get full IDE support with autocomplete and type checking, access to the entire npm ecosystem, and the ability to unit test your policies like any TypeScript function. Your team’s existing TypeScript skills transfer directly.

Transparent Pricing

Instead of navigating Azure APIM’s multi-tier pricing model where each environment costs hundreds or thousands per month, Zuplo offers straightforward pricing with a free tier to get started. Preview environments are free, and you don’t pay per-instance for dev and staging.

Faster Deployments

Azure APIM deployments take 15–45 minutes. Zuplo deployments complete in under 20 seconds to all 300+ edge locations. That’s a significant improvement for development velocity and incident response.

Frequently Asked Questions

Can I migrate from Azure APIM without changing my backend services?

Yes. Zuplo proxies requests to your existing backends — including Azure App Service, Azure Functions, AKS, and Azure Container Apps — using the URL Rewrite or URL Forward handler. Your backend services do not need any changes.

How long does an Azure APIM migration typically take?

For most teams, a complete migration takes two to four weeks. Teams with straightforward configurations (standard authentication, rate limiting, and proxying) can often complete the migration in under a week. Complex setups with many custom C# policy expressions may take longer.

What replaces Azure APIM subscription keys in Zuplo?

Zuplo’s built-in API key authentication policy provides managed API key services. You can create consumers with metadata, issue keys validated at the edge, and let developers self-manage keys through the developer portal. Existing keys can be imported via the Zuplo Developer API.

Does Zuplo work with Azure AD (Entra ID) for authentication?

Yes. Zuplo’s JWT Auth Policy validates tokens from any OpenID-compliant provider, including Microsoft Entra ID. Configure the policy with your Entra ID issuer URL and audience, and Zuplo validates tokens at the edge automatically.

Can I run Zuplo alongside Azure APIM during migration?

Yes. The recommended approach is to run both gateways in parallel during the cutover phase, using DNS or Azure Front Door to gradually shift traffic from Azure APIM to Zuplo.

Next Steps

Ready to migrate? Sign up for a free Zuplo account and follow the Getting Started Guide to set up your first gateway in minutes.

For planning your migration:

Compare Zuplo and Azure API Management — see a detailed feature-by-feature comparison.
Azure APIM Migration Guide (Zuplo Docs) — the technical reference for Azure APIM migration in the Zuplo documentation.
Policy Catalog — browse all available built-in policies.
Custom Policies Documentation — learn how to write your own TypeScript policies.
Migrating from Self-Hosted to Managed API Gateway — for general migration strategies and zero-downtime patterns.