API Gateway Migration Playbook: Keep Security Controls

An API gateway migration quietly rewrites the security controls in front of every API at once, and any control that lived only in the old gateway's configuration disappears unless someone deliberately moves it. Organisations change gateways for many reasons: a move between clouds, a self-hosted product reaching end of support, consolidation after an acquisition, or a shift from a central edge gateway to a service mesh or per-team gateways. Authentication, token validation, rate limits, request size limits, allowed methods, CORS rules and logging are all typically enforced in gateway policy, so a migration is really a security control migration. This playbook is vendor-neutral and written for platform, API and security engineers who own the move. It covers the inventory, policy translation, the gateway's own credentials, a phased cutover with rollback, and decommissioning. Hardening a gateway in steady state is covered in the API Gateway Security Guide; standing up a first gateway is covered in the API gateway rollout playbook.

Key takeaways

Inventory routes, not just APIs. Every route, version, host name and consumer credential on the old gateway needs an owner and a decision: move, merge or retire.
Translate policy as code and test it as code. Gateways express the same control differently, and silent defaults (no size limit, permissive CORS, algorithm taken from the token header) are where protection is lost.
Re-issue consumer credentials where you can. Migrating API keys and client secrets by copy carries every leaked key forward; issuing new ones retires them.
Close the back doors. The old gateway and direct back-end paths must stop answering, otherwise attackers simply route around the new controls.
Measure parity before you switch. Compare rejection rates, status codes and latency per route between old and new during a shadow phase, and keep a tested rollback.

What actually has to move

A gateway holds far more than routing rules. OWASP API Security Top 10 2023 item API9, Improper Inventory Management, describes a real pattern: rate limiting was enforced in a component in front of the production API, but a beta host ran the same API without it and a researcher brute forced six-digit password reset tokens there. A migration creates exactly this situation if a single route or host is missed. Build the inventory by object type.

Object	Why it matters in a migration	Typical decision
Routes, paths and host names	Each route is an entry point; unlisted routes become unprotected after cutover or keep running on the old platform	Move, merge or retire with a named owner
API versions and deprecated endpoints	Old versions often have weaker checks (API9) and are rarely re-tested	Use the migration to retire versions with a published sunset date
Authentication policies	API key checks, JWT validation, mutual TLS, introspection calls and external authorisation hooks	Translate and test each one; see the table below
Consumer records, API keys, client IDs and secrets	Long-lived credentials held by partners and internal services	Re-issue where possible; copy only with a rotation deadline
Rate limits, quotas and usage plans	Protect against brute force and resource exhaustion (API4:2023)	Translate per consumer and per route, then load test
Request validation and transformation	Schemas, size limits, allowed methods and content types, header injection or stripping	Translate; review transformations that add identity headers
TLS certificates and trust stores	Server certificates, client CA bundles for mutual TLS, upstream TLS settings	Issue new server keys on the new platform; never export private keys by email or ticket
Upstream credentials	Credentials the gateway uses to call back ends, identity providers and logging sinks	Create new, narrowly scoped credentials for the new platform
Logging and analytics configuration	Audit trail for token validation errors and access decisions	Map fields so detections keep working; retain old logs

Pull the route list from the gateway itself, then reconcile it against DNS records, load balancer listeners, OpenAPI specifications in source control and actual traffic logs. Routes seen in traffic but missing from specifications are the ones nobody will remember to test. For the governance side of discovery, see the OWASP API Top 10 API9 Improper Inventory Management Guide.

Translating security policy without losing it

No two gateway products express controls in the same way, and the migration tooling some platforms offer converts syntax, not intent. Treat translation as a security review. The OWASP REST Security Cheat Sheet gives a useful parity list: reject unsigned JWTs such as {"alg":"none"}, take the verification algorithm from configuration and never from the token header, require and validate iss, aud and exp (and nbf when present), allowlist HTTP methods and answer others with 405, enforce a request size limit with 413, reject unsupported content types with 415, and return 429 when rate limits are hit.

Control	Where it silently breaks during translation	Parity test
JWT signature and algorithm	New platform accepts any algorithm listed in the key set, or reads `alg` from the token	Send tokens signed with an unexpected algorithm and with `alg` set to none; expect 401
Issuer and audience	Audience check left blank, so tokens for other APIs are accepted	Replay a valid token minted for a different resource server; expect 401
Expiry and clock skew	Default leeway is much larger than the old setting	Present a token expired by more than the agreed skew
Scopes and claims to route mapping	Scope checks applied per API instead of per operation	Call write operations with a read-only token
Mutual TLS and certificate-bound tokens	TLS terminates at a new load balancer, so the gateway never sees the client certificate	Present a token bound to certificate A over a connection using certificate B; expect 401 with `invalid_token`
Rate limits	Limits become per node instead of cluster-wide, multiplying the real allowance	Load test from one consumer across all nodes
Size, method and content type limits	New default is unlimited or permissive	Send oversized bodies, TRACE and unexpected media types
CORS	Wildcard origins copied from a test environment	Preflight from an unlisted origin
Error handling	Verbose upstream errors or stack traces passed through	Force a back-end 500 and inspect the response body

The mutual TLS row deserves special attention. RFC 8705 binds an access token to a client certificate through the cnf claim with an x5t#S256 thumbprint, and the resource server must compare that thumbprint with the certificate presented on the TLS connection and reject a mismatch. If the new architecture terminates TLS earlier, the binding is lost unless the certificate is passed through in a trusted way. RFC 9700, the OAuth 2.0 Security Best Current Practice, also recommends audience-restricted and sender-constrained access tokens, so a migration is a good moment to add them rather than drop them.

Keep the translated policy in source control, reviewed like application code, with automated tests that run the parity checks above against every environment. Where the new platform supports an external policy engine, decide whether to move authorisation logic there now or later; changing two things at once makes failures harder to diagnose. The API Security Guide covers the underlying patterns.

Where identity fits: consumer and gateway credentials

Most of the credentials in a gateway migration belong to non-human identities: partner integrations, internal services, mobile back ends and the gateway itself.

Consumer API keys and client secrets: issuing new credentials on the new platform is cleaner than exporting old ones. The OWASP cheat sheet notes that API keys alone should not protect sensitive or high-value resources; the migration is a natural point to move high-value consumers to OAuth client credentials or mutual TLS. Publish a rotation deadline and disable old keys once traffic stops. See the API Key Management Guide and API Keys vs OAuth Tokens Guide.
Exported key material: if keys must be copied because consumers cannot change quickly, move them through a secrets manager, never through spreadsheets or tickets, and record which keys were copied so they can be rotated first.
The gateway's own credentials: the new gateway needs credentials for the identity provider (introspection or client credentials), upstream services, certificate issuance and log shipping. Create new ones with minimum scope rather than reusing the old platform's.
The migration identity: whoever or whatever reads the old configuration and writes the new one holds administrative rights on both platforms. Make it time-limited, logged and removed at the end.

The Imperva breach shows the cost of migration leftovers: according to the company's update, a database snapshot created for testing during its 2017 move to AWS sat on an internal compute instance that was reachable from the internet, and an administrative API key taken from that instance was later used to reach the data.

The phased playbook

Freeze and baseline. Announce a change freeze on gateway policy, export the full configuration from the old platform, and capture two to four weeks of per-route metrics: request volume, status code mix (401, 403, 413, 415, 429), latency and top consumers.
Inventory and decide. Reconcile routes against specifications, DNS and traffic. Assign each route an owner and a decision. Retire unused versions with notice.
Build the target with secure defaults. Deploy the new gateway with administration interfaces on a separate network, administrators behind single sign-on and phishing-resistant MFA, and deny-by-default routing so only explicitly defined routes answer.
Translate and test policy. Convert policies, then run the parity tests from the table above in a pre-production environment, including negative tests.
Shadow traffic. Where the platform allows it, mirror a copy of production requests to the new gateway with responses discarded, and compare allow and deny decisions per route. Investigate any route where the new gateway allows a request the old one rejected.
Canary cutover. Shift a small percentage of traffic, or one low-risk consumer group, using weighted DNS or load balancer rules. Increase in rings, for example 1, 10, 50 and 100 percent, with a hold period at each step.
Rollback plan. Keep the old gateway running and its credentials valid until the final ring has held for an agreed period. Rollback is a traffic switch, not a rebuild, and should be rehearsed once before go-live.
Close direct paths. Once all traffic flows through the new gateway, restrict back-end ingress so it only accepts the new gateway, for example by network policy, private connectivity or mutual TLS between gateway and service.
Decommission. See the next section.

Decommissioning the old gateway

An old gateway that still answers requests is an unmonitored, unpatched copy of your API perimeter. Decommissioning is a security task with its own checklist.

Stop traffic, then watch: switch the old gateway to return errors and alert on every request it receives for a period; stragglers reveal forgotten consumers and hard-coded IP addresses.
Revoke credentials: disable consumer keys that were re-issued, revoke the old gateway's own client registrations at the identity provider, and remove its certificates from upstream trust stores.
Remove DNS and listeners: delete DNS records and load balancer listeners pointing at the old platform so the host names cannot be taken over or reused unexpectedly.
Keep the evidence: retain old gateway logs for the period your logging policy requires before deleting the platform.
Sanitise: destroy configuration exports, backups and private keys in line with NIST SP 800-88 Rev. 2 or the provider's documented deletion process.
End the contract cleanly: for a managed gateway, confirm deletion of tenant data with the provider, as NIST CSF 2.0 outcome GV.SC-10 expects plans to cover activities after a partnership ends.

Decision guidance

Choice	Option A	Option B	Choose A when
Cutover style	Big bang switch	Canary rings by route or consumer	Few routes, few consumers and a short maintenance window is acceptable
Consumer credentials	Re-issue	Copy with rotation deadline	You control the consumers, or partners can update within weeks
Architecture	Like-for-like central gateway	Central edge plus service mesh	Teams lack mesh skills; NIST SP 800-204 and SP 800-228 discuss both patterns
Policy language	Native gateway policies	External policy engine	Authorisation rules are simple and owned by one team

Small organisations: with a handful of APIs, a single weekend cutover with full negative testing and a rehearsed DNS rollback is often safer than a long dual-running period that nobody monitors. Large organisations: migrate by domain or business unit, publish a route registry, and use automated parity tests in every pipeline; expect long tails of partner consumers and plan for them explicitly.

Detection and measurement

Log every token validation failure and access decision on the new gateway, as the OWASP cheat sheet recommends, and make sure the field mapping keeps existing detections working. Alert on requests reaching the old gateway after cutover, on requests reaching back ends that did not pass through the gateway, and on sudden drops in 401 or 429 responses, which often mean a check has gone missing rather than that attacks have stopped.

Route coverage: percentage of routes seen in traffic that are in the registry with an owner (target 100 percent).
Policy parity: percentage of routes passing the full negative test suite on the new gateway.
Decision drift: requests allowed by the new gateway that the old gateway would have denied during shadowing (target zero before cutover).
Credential re-issue: percentage of consumer credentials re-issued rather than copied, and days until copied ones are rotated.
Residual traffic: requests to the old gateway and direct back-end requests after cutover (target zero).
Time to decommission: days from final ring to old platform deletion.

Common failure patterns

The forgotten host: a beta, partner or legacy version host stays on the old gateway or is migrated without its rate limits, matching the API9 scenario.
Audience checks dropped: the new configuration validates signatures but not aud, so any token from the same identity provider works on every API.
Per-node rate limits: a limit of 100 requests per minute becomes 100 per node, and brute-force protection weakens without anyone noticing.
Direct back-end access left open: services remain reachable by their internal or cloud load balancer addresses, so attackers bypass the gateway entirely.
Keys copied and never rotated: old consumer keys, some already leaked, carry on working indefinitely on the new platform.
Test environments left running: snapshots and instances created for migration testing hold real data and credentials, as in the Imperva case above.

Framework mapping

Migration activity	NIST SP 800-53 Rev. 5	NIST CSF 2.0	Other references
Route and API inventory	CM-8 System Component Inventory	ID.AM-02, ID.AM-03	OWASP API9:2023
Policy translation and change control	CM-2 Baseline Configuration, CM-3 Configuration Change Control	PR.PS-01	NIST SP 800-228
Consumer and gateway credentials	IA-5 Authenticator Management, AC-6 Least Privilege	PR.AA-01, PR.AA-05	RFC 8705, RFC 9700
Closing direct paths and TLS	SC-7 Boundary Protection, SC-8 Transmission Confidentiality and Integrity	PR.DS-02	ATT&CK T1190 Exploit Public-Facing Application
Logging and monitoring	AU-2 Event Logging, AU-11 Audit Record Retention	PR.PS-04, DE.CM-09	OWASP REST Security Cheat Sheet
Decommissioning	SR-12 Component Disposal, MP-6 Media Sanitization	PR.PS-02, GV.SC-10	NIST SP 800-88 Rev. 2

Practitioner checklist

Export the full old gateway configuration and baseline per-route metrics before any change.
Reconcile routes against specifications, DNS and traffic logs; give every route an owner and a decision.
Translate policies as code and run negative tests for algorithm, issuer, audience, expiry, scopes, size, methods and CORS.
Confirm mutual TLS and certificate-bound tokens still work after any change in TLS termination.
Re-issue consumer credentials where possible and set deadlines for any that were copied.
Create new, minimal credentials for the new gateway and a time-limited migration identity.
Shadow traffic and compare allow and deny decisions before the first canary ring.
Rehearse rollback as a traffic switch and keep the old platform intact until the final ring holds.
Restrict back ends so they only accept traffic from the new gateway.
Decommission: alert on residual traffic, revoke credentials, remove DNS, retain logs and sanitise exports.

API gateway migration playbook: moving platforms without losing control