Export APIs and policies from Azure API Management

What you can export from Azure API Management and what you cannot

If your Azure API Management contract is up for renewal, changing tiers or ending, you need a clean copy of your APIs and policies before the contract ends, because the service will not hold the state you left it in. APIs, policy XML, products, named values and diagnostic settings can be extracted with the open-source APIOps tooling, which reads the service configuration and writes it to files you can version. Secrets, subscription keys, developer accounts and developer portal content need separate handling, and each one needs an owner and a plan. This section sets the boundary so you can scope the work before you run anything.

Start with what the export covers, because that determines what you can test on a new gateway before cutover. API definitions, their operations and revisions, the policy XML attached at the global, product, API and operation scopes, products and their API membership, named values, and diagnostic settings are all configuration objects that can be written out as files. Keep those files in a Git repository so every change is visible and reviewable. Confirm with the tool's documentation how it handles secret named values, since the value of a secret may not come back in plain text. Inventory every named value that feeds a backend URL, header or credential so you know what to re-enter. Diagnostic settings also point to Application Insights or Log Analytics resources, which will not follow your APIs to a self-hosted gateway.

Expect several things to stay behind. Subscription keys are issued by the Azure service, so plan to reissue them on the new gateway and notify each subscriber in advance. Developer accounts and their passwords are not part of a configuration export, so decide whether consumers will re-register or sign in through a shared identity provider. Developer portal content, including customized pages, templates and uploaded files, needs its own export or a rebuild in the new portal. Backend credentials, client certificates and Key Vault references must be recreated in your target secrets store. Before the renewal date, run a test export, compare the output against the live service with a named owner for each API, and record which items are exported, which are re-created and which are retired.

Which Azure API Management data types export, by method and format

This table lists each Azure API Management configuration type, the export method, the output format and what to verify before you rely on the export. Use it as a checklist: compare the exported files with your tenant's object names and counts before you treat the export as a migration input. Confirm current extractor behavior in the APIOps documentation and in your own tenant, because coverage can change between versions.

Data type	Export method	Output format	Confirm before export
APIs and operations	APIOps extractor reads the service	Files per API, including specification and metadata	Revisions, versions and operation-level detail are captured
Policy XML at global scope	Extractor reads the service-level policy	Single policy XML file	Whether it is included with the service configuration
Policy XML at product, API and operation scope	Extractor reads each scope's policy	Policy XML files stored beside their owning object	Named value references and expressions are preserved as written
Products	Extractor reads product definitions and API links	Metadata files per product	Subscription and approval settings are included
Named values	Extractor reads named value definitions	Metadata files; secret values may need separate handling	Whether secret values are exported and where they are stored
Diagnostics and loggers	Extractor reads diagnostic settings	Metadata files with logger resource references	Logger destinations exist in the target environment
Tags	Extractor reads tag definitions and assignments	Metadata files linked to APIs and products	Tag assignments at API and operation level are complete
Version sets	Extractor reads version set definitions	Metadata files linked to versioned APIs	Version identifiers and the versioning scheme are preserved

What does not come out cleanly and how to work around it

A configuration export captures APIs, policies and products, but several things live outside the definitions or are never returned in readable form. Each item below needs a deliberate plan before the export is treated as a complete migration input.

Secret values in named values

Named values marked as secret are typically exported as references rather than their plaintext values, so policies that read them will break on the new gateway until the values are supplied. Inventory every named value that a policy references, then load the real values into your own secrets manager and map each one to a gateway variable or plugin configuration key. Confirm with Microsoft's current documentation how secret named values appear in your export format, and do not assume the exporter returns them.

Subscription keys and consumer credentials

Subscription keys are generated by Azure API Management and are not portable, so clients that send them will fail on the new gateway. Plan to issue new credentials on the target platform, give consumers a dated cutover window, and accept that some clients will need a configuration change. Confirm whether your consumers can accept a new key or need a token-based scheme that the target gateway can validate.

Developer accounts and passwords

Developer portal accounts and their password hashes are held by the Azure service and are not exported as usable records. Consumers will need to register again or be migrated through an identity provider that both platforms can trust. Before deciding, list which accounts are active, which belong to partners, and whether your identity provider can federate them. Confirm with your legal and privacy team what notice consumers must receive.

Developer portal customizations and content

Portal pages, custom widgets, styling and uploaded documents are part of the portal's content and do not come out as a configuration export. Treat the portal as a rebuild: copy the API documentation from the source definitions, recreate branding and custom pages on the target portal, and record every manual change in your migration log. Check which content lives only in the Azure portal's editor so nothing is lost at decommissioning.

Analytics history and logs

Request metrics, usage reports and diagnostic logs stay in Azure and are not moved with the APIs. Decide which history you need for audits, chargeback or SLA reviews, then export it to your own log store before the subscription is changed. Ask Microsoft what retention applies to your tier and whether your export format fits your existing tooling, and set a date after which the data is no longer needed.

Managed identity bindings

Managed identities are tied to the Azure resource and to Microsoft Entra ID, so policies or backends that call other services with them cannot run unchanged elsewhere. Map each binding to a workload identity your target platform can use, such as a client credential or a token issued by your own identity provider, and grant it the same scopes. Confirm with your identity team which downstream services accept the new identity before cutover.

How the APIOps export feeds a target gateway

The export runs in one direction. The Azure API Management service is read, its APIs, policy XML, products, named values and diagnostic settings are written to files, those files are committed to a source control repository, and a target gateway or control plane is populated from that repository. Each step is a checkpoint you can verify. Confirm that the extraction identity has read-only rights on the API Management instance you plan to retire, and label each export with the instance it came from. On the target side, the mapping work happens between the export and the target's configuration. For example, a file-driven Apache APISIX standalone deployment reads a YAML or JSON file and reloads it when the file changes, so policy XML has to be translated into that file's structure before anything goes live.

The trust boundary sits where exported files leave the Azure tenant. Once they are in a repository, they describe your whole API estate: backend URLs, operation definitions, rate limits, authentication settings and references to named values, some of which may hold credentials. Treat that repository as a sensitive system. Restrict read and write access to a named group, require review before changes reach the main branch, and keep secret values out of the exported files by pointing them at the target's own secret store. Confirm where the repository is hosted, which jurisdiction applies to it, and who on your team and on any partner's team can clone it. Keep its access logs for as long as the migration is active.

Store each export as a dated snapshot and record the commit that each cutover was based on. Before any traffic moves, load the exported files into the target in a non-production environment and compare the routes it exposes with the APIs listed in the export. Resolve the gaps that are simplest to miss first, such as an operation without a backend, a product that was never linked to an API, or a named value that the target cannot resolve. Ask the team that will run the target how it authenticates to the repository and how it pulls changes, so that a leaked token cannot quietly change a live gateway.

The complete export sequence, step by step, with verification

This sequence takes an Azure API Management instance from inventory to a verified, version-controlled export. Each step produces a file, list or check result that the next step depends on. The result is a repository that a migration team can review, diff and reuse, with secrets and portal items tracked separately.

Inventory the instance and its tiers
The platform engineering lead lists every API Management instance in scope, with its service tier, region, custom domains, and whether it runs in a virtual network or uses a self-hosted gateway. Record the number of APIs, products and subscriptions shown in the portal, and note the tier of each instance, since the tier determines which features the export can cover. Save the inventory in the migration repository. It is done when every instance has a row in the inventory and a second person has reviewed it.
Create a read-only identity for extraction
An administrator creates a dedicated identity, such as a managed identity or service principal, and grants it read access only to the instance and its resource group. Confirm the exact built-in role names in Azure's access control documentation before assigning them. Document the role, the scope and the date granted in the runbook. Then test the identity in a sandbox instance by attempting a write, which should fail, and a read, which should succeed. It is done when the runbook records both results.
Run the extractor against a non-production copy
Before touching production, the team runs the APIOps extractor against a non-production instance or a restored copy, writing output to a clean working folder. Check the run log for errors and warnings, especially for policy fragments, named values and products that did not extract. Confirm that the output folder contains an API folder for every API in the inventory. It is done when the run completes without unexplained errors and the counts match the portal. Record any skipped items as open issues and do not assume they are empty.
Export production and commit to Git
Run the same extraction against production with the read-only identity, then commit the output to a Git repository and tag it with the date and instance name. Keep policy XML, OpenAPI definitions, products, subscription metadata, named values and diagnostic settings in separate folders so each review stays focused. Do not commit credentials, tokens or certificate files. Add them to an ignore list and run a secret scanner over the commit. It is done when the scanner reports no findings and a second engineer can check out the tag and read the export.
Inventory secrets, named values and certificates
Named values marked as secret, backend credentials, client certificates, subscription keys and Key Vault references may not export as plain values, so confirm how the tooling handles each type. List every item with its owner, the APIs that use it and the planned location in the target gateway. Mark each item that a person must re-enter. Add developer portal sign-in and identity provider settings to the list. It is done when every secret-bearing item has a row, an owner and a target location, and the security team has approved the list.
Export portal and diagnostic settings
Capture what the API extractor does not cover. Export developer portal content and settings through the portal's own mechanisms, record sign-up and delegation settings, and note the identity providers configured for developers. Record diagnostic settings, logger destinations and log retention for each instance so monitoring can be rebuilt. Store these as files in the same repository. It is done when portal content, logger targets and diagnostic destinations each appear in the repository or in the inventory with a named owner.
Verify with a diff and object counts
Run a fresh export from the same production instance on a later day, then diff it against the first commit. Ignore fields that change on every run, such as timestamps and generated identifiers, but treat any change to policy XML, operation paths, product membership or named value names as a finding. Compare the counts of APIs, operations, products, policies and subscriptions with the portal. A failed check looks like a count mismatch, an API with no policy file where the portal shows one, or a change in a policy body that nobody edited. It is done when every mismatch is explained in writing or fixed and re-exported.

Export approach for a single instance versus many instances

A single API Management instance with a modest number of APIs can usually be exported in one pass. Start by confirming which APIs, products, named values and policy fragments the instance holds, then run the APIOps extractor against a non-production copy or a read-only identity so you can review the output before anything moves. Keep the export in version control so each run produces a diff you can read. The decisions that stay simple at this size are whether to keep one gateway cluster and how many environments you need to reproduce.

Inventory first: List APIs, products, subscriptions and named values in the portal so you can check the export against a known count.
Single extraction run: Export into a Git repository, then review the policy XML and named values in one sitting.
Secrets handled separately: Named values marked secret and certificates are not written to the export in plain form, so plan how you will recreate them in the target.
One target cluster: A single APISIX or Gravitee deployment is often enough, so you can cut over by moving DNS for the whole instance at once.
Rollback path: Keep the Azure instance running until the target has passed your tests.

Before you start, confirm with your team which exporter version you will use and what your Azure role must allow, because permissions decide what the export can read.

What to plan before the Azure API Management contract ends

Exporting configuration is only one step. The cards below cover the commercial, technical and legal decisions that determine whether the export is usable and whether traffic can move without an outage. Work through them before the renewal or termination date is fixed, because several depend on what Microsoft allows you to do after the subscription stops.

Confirm tier and reserved capacity terms

Check which Azure API Management tier you run, how many units you pay for, and whether any capacity is reserved under a commitment. Ask Microsoft in writing what happens to committed spend, prorated charges and the gateway units if you reduce or stop before the term ends. These terms set how long you can run in parallel and what the overlap costs, so settle them before you choose a cutover window.

Record the last usable export

Set a date after which you will no longer change policies in the portal, and take a full export on that date with the APIOps tooling. Store the output in version control with the API Management instance name, region and export timestamp. Any later edit made in the portal will be missing from the migration, so freeze changes or have a second export run before cutover.

Plan parallel running

Deploy the target gateway next to Azure API Management and send a share of test traffic through both. Compare status codes, latency, rate-limit behavior and JWT validation results for the same requests. Keep the Azure gateway serving production until the target has matched its behavior for each API, so you can roll back a single API without reverting the others.

Schedule DNS and certificate changes

List every hostname that points at the Azure gateway, including custom domains, and the TLS certificates bound to them. Lower DNS record time-to-live values well before the change, and issue or import certificates for the new gateway ahead of time. Move one API at a time, and confirm that clients trusting a specific certificate chain or pinning a fingerprint still connect after each switch.

Keep the subscription active until traffic moves

Do not let the Azure API Management instance lapse, be deleted or be downgraded while any consumer still calls it. Deleting the service removes its keys and developer portal content, so the export and the new gateway must be verified first. Plan the final shutdown as the last step, after logs show no remaining calls to the old hostnames for an agreed observation period.

Confirm retention and deletion in writing

Ask Microsoft to confirm in writing how long diagnostic logs, analytics and backups for the instance are kept after deletion, and when they are removed. Also confirm how the developer portal data and subscription keys are handled. Your own records, including exported policy files and audit logs, must follow your retention schedule, so record the answers in your contract file and your data inventory.

Questions buyers ask before exporting Azure API Management

How much effort does exporting from Azure API Management take?

The export itself is usually the smaller part of the work, and its effort depends on how much configuration you have. The main drivers are the number of APIs, the complexity of policy XML (especially nested conditions, backend calls and custom transformations), how many named values and secrets you use, and how much you have customized the developer portal. Each of these adds review work because the export gives you files, not an equivalent running configuration. Ask the implementation partner to inventory these four areas before agreeing on scope, since that inventory is what the rest of the estimate rests on.

Can our team run the export without an outside partner?

Yes, for a small estate with simple policies, a team familiar with Azure and Git can run the APIOps tooling and review the output. The harder parts are judgment calls: deciding which policies become APISIX plugins, which need custom code, and how credentials move without being written into the repository. Teams with many products, subscriptions and portal customizations often bring in outside help for the mapping and the cutover plan. Whichever route you take, a written scope makes it clear who owns each deliverable.

What skills does the internal team need for the export?

The export needs three skill sets. Azure skills are needed to read the service configuration, access the management plane and understand the tier you are on. Git skills are needed to store the exported files as a versioned source of truth and to review changes through pull requests. Gateway skills are needed to read policy XML and judge how each rule behaves in the target gateway. Few teams have all three in depth, so plan for a pairing of an Azure owner with someone who knows the target gateway. Confirm the APIOps tooling version and its supported resources with the project before you start.

How long does the export take, and what sets the pace?

The duration depends on the factors listed above, along with how quickly your organization can approve the export scope, access credentials and review the output. Pace is usually set by policy review and by the people who must sign off on security-sensitive settings, not by the extraction command. We do not supply a duration here. Ask for a timeline tied to a written list of APIs, products and portal items, with named review checkpoints.

What does the export cost, and which costs are one-time?

Cost has several components: staff time for the export and review, engineering time to convert policies, a test environment, and any partner fees under a fixed-scope agreement. Most of the export and conversion work is one-time. Recurring costs begin when the target platform runs in production, including hosting, upgrades, certificate and secret management, and monitoring. Your Azure subscription costs continue until you retire the service, so include an overlap period in your comparison. Azure's own pricing is set by tier and unit, so check your current bill rather than relying on published figures.

How are secrets and named values handled during the export?

Treat the export as sensitive data. Named values marked as secret, subscription keys, client secrets and certificates should not be committed to a Git repository in plain text. The usual approach is to export structure and reference secrets by name, then load their values from a secrets manager in the target environment. Confirm with your security team where secrets will be stored, who can read them, and how rotation will work after cutover. Access to the exported files should follow the same controls as the source configuration.

What should we ask for in a quote for this export?

Ask for a written scope that lists the APIs, products, named values, policy sets, diagnostics and developer portal items in scope, along with what is excluded. Request a deliverables list covering the exported repository, a mapping table from each Azure policy to its target equivalent, a list of policies that need custom work, and a cutover plan. Ask who owns secrets handling, what testing is included, what support follows the handover, and how changes after the scope is agreed will be priced. DeployOpen does not publish a price list, and a quote follows from that written scope.

Turning the export into a migration plan

Treat the export as an inventory to sort, not a file to copy. Classify each API along two axes: how many consumers depend on it, and how much harm an outage or a misrouted request would cause. Consumer count is not visible in the exported XML, so pull subscription and key usage from your Azure API Management analytics and diagnostic logs before you decide. Low-consumer, low-risk APIs make good pilots for the target gateway. High-consumer APIs, and those that handle regulated or payment data, move last, once the team has a proven pattern for authentication, rate limiting and logging.

Map policies by intent, not by XML element. Inbound rate limits, JWT validation, header transformations, caching and backend routing usually have a counterpart in the target gateway, but the mechanism changes. Some policies will need a rebuild rather than a direct copy: expressions that depend on Azure-specific context, named values that point to Azure Key Vault, and logic that calls external services in ways the target cannot reproduce. Record a keep, copy or rebuild decision for each policy. The detailed mappings belong on the sibling migration pages for APISIX and WSO2 API Manager. Validate every mapping in a test environment with representative traffic and with negative cases, such as expired tokens and exceeded limits.

Sequence the cutover API by API. Run the new route in parallel, shift traffic one API at a time, and keep the Azure route ready as a rollback path until error rates and latency look right. Decide early how developer accounts, subscriptions and keys will move, and whether consumers must re-issue credentials. Freeze policy changes in Azure API Management for each API during its window so the export stays accurate. Keep the exported files in version control as the baseline for the migration, and confirm with each consumer team which rollback window they need before you begin.

How DeployOpen works on this

DeployOpen plans and implements self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For an Azure API Management export, we scope the inventory, run the extraction in your environment and deliver a documented, tested exit package that your team can act on.

How we scope

Written scope lists every API, product, named value, policy set and developer portal asset to be extracted
We agree which Azure subscriptions, resource groups and environments the export covers before work starts
Secret handling, credential rotation and who holds exported material are defined in the written scope

How we build

We run the APIOps extraction in your environment so policy XML and configuration stay under your control
Exported policies are reviewed and mapped to the target gateway, with gaps recorded as explicit findings
Each export is validated against a copy of the live configuration to confirm completeness before cutover planning

How we hand over

You receive a documented inventory, a policy mapping table and a sequenced migration plan, API by API
Runbooks cover DNS switching, subscription and key re-issuance and rollback steps for each API group
Handover includes a walkthrough with your platform, security and API owner teams to confirm acceptance

How we support

Engagements are fixed-scope, with deliverables and timelines agreed in writing before work begins
Ongoing support, upgrades and continuous testing of the target gateway are available as a retainer
Quotes follow from the written scope, so ask for the export, mapping and handover items to be itemized

How to export APIs and policies from Azure API Management