Legacy ArcGIS API keys retire June 27, 2026 — what breaks, and how to migrate

If an app you run still authenticates to ArcGIS location services with a key you created before June 27, 2024, your deadline is measured in days, not months. On June 27, 2026 Esri revokes every legacy API key. The apps won’t crash — they’ll keep loading, and then quietly fail the first time they ask for a basemap, a geocode, or a route.

That silent-failure mode is what makes this dangerous. A hard crash gets noticed in five minutes; a map that loads but won’t geocode can sit broken for a week before a client reports it. Here is exactly what is retiring, how it fails, and the migration path — including the wrinkle most write-ups miss: the replacement privileges differ depending on whether you mint the key from ArcGIS Online or ArcGIS Location Platform.

What exactly is “legacy”

A legacy API key is any API key created before June 27, 2024 — the day Esri shipped the new developer-credentials experience. You can tell them apart by how they were made, not by the string: legacy keys came straight off the old developer dashboard, never expire, and can only be scoped to location services and privately shared items. Esri walked them through a deliberate lifecycle:

• June 2024 — mature support. Legacy keys can no longer be created or edited; API key credentials become the replacement.
• June 2025 — extended support. The June 2026 retirement date is announced.
• June 27, 2026 — revoked. Legacy keys can no longer authenticate with ArcGIS services.

They’re being retired for good reasons: legacy keys never expire, they can only reach location services and private items, their scope can be changed without invalidating the existing token (a security weakness), and ArcGIS Enterprise users could never create them at all.

How it fails — and why it looks like nothing’s wrong

The SDK initializes fine. The view paints whatever is cached. Then the first authenticated request goes out and comes back rejected:

# A request that worked yesterday, after June 27
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates
    ?f=json&singleLine=380+New+York+St,+Redlands&token=AAPK…legacy-key…

→ HTTP 498  { "error": { "code": 498, "message": "Invalid token." } }

Because only the authenticated calls fail, the breakage is patchy and easy to miss: an OSM or cached basemap may still draw while geocoding, routing, places, and premium basemaps all go dark. Treat any app that hard-codes or environment-injects an ArcGIS key as in-scope until you’ve proven otherwise.

The replacement: API key credentials

The successor is the API key credential — an ArcGIS content item that creates and manages the actual API keys, rather than the bare key you got before. It is a drop-in replacement for the same location-service privileges, and it adds a lot:

Two operational changes are worth flagging before you start. First, an API key is now shown only once, at creation — copy it straight into your secret store, because you cannot view it again. Second, editing a credential’s expiration date or privileges changes the key string. You cannot tweak a key in place and expect the old string to keep working, which is exactly why the credential supports holding two keys at once: rotate, deploy, then retire the old one.

The dual-account wrinkle: Online vs Location Platform

If you, like us, run both an ArcGIS Online organization and an ArcGIS Location Platform account, the migration is not identical on both sides. When a legacy scope becomes a credential privilege, Location Platform keeps fine-grained control while ArcGIS Online collapses several scopes into one. Same app, different privilege wiring depending on where you mint the key:

Two practical takeaways. If your app needs granular routing (say, optimized routing but nothing else) or the Places service, mint the credential from Location Platform — ArcGIS Online folds all network-analysis operations into one privilege and doesn’t expose Places the same way. And on ArcGIS Online the basemap-styles privilege can’t be disabled, so an Online key always carries basemap access whether you wanted it on that key or not. Choosing the right account up front saves you re-issuing keys later.

Migrate in seven steps

1. Inventory every app, notebook, and service that carries an ArcGIS key. Anything with a string starting AAPK created before June 27, 2024 is in-scope.
2. Open each legacy key’s item page and note its assigned scopes — this is your privilege checklist for the replacement.
3. Decide which portal to mint from — ArcGIS Online or Location Platform — using the privilege table above.
4. In that portal, create a new credential: My content → New item → Developer credentials → API key credentials.
5. Assign privileges that recreate the legacy scopes, set an expiration (up to a year) and lock down referrer URLs to your real domains.
6. Save, then copy the generated key to your secret store immediately — it is shown only once.
7. Swap the key string in your app, deploy, and verify a live geocode/route/basemap call before you retire the old key.

The code around the key usually doesn’t change — only the string does. In the ArcGIS Maps SDK for JavaScript it’s still one assignment, and it should never be hard-coded:

import esriConfig from "@arcgis/core/config.js";

// the only thing that changed is the value — keep it in an env var, never in source
esriConfig.apiKey = import.meta.env.VITE_ARCGIS_API_KEY;

Do this now, not on the 27th

Migration is reversible-friendly — you can run the new key alongside the legacy one and cut over the moment it verifies. There is no upside to waiting, and a real downside to discovering on launch day that an app you forgot about goes dark in production. Inventory today; the keys themselves take minutes.

References

• API key (legacy) retirement — Esri Developer documentation (timeline, advantages, scope→privilege mapping, 7-step migration)
• Legacy API Keys Retirement — Esri Support (Article 000036479)
• Developer credentials: What’s new and improved — ArcGIS Blog
• Tutorial: Update to API key credentials