API key (legacy) retirement

API keys (legacy) are permanent access tokensAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more created before June 2024 that were used for accessing ArcGIS location servicesArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services.Learn more. Legacy API keys can no longer be created, and must be replaced with API keys generated from API key credentialsAPI key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential.Learn more.

This page contains essential information for updating your applications:

• Retirement timeline
• Advantages of using API key credentials
• How to switch to API key credentials

Example of a legacy API key item

Retirement timeline

This timeline shows the lifecycle and deprecation of API keys (legacy)An API key (legacy) is a permanent access token created before June 2024 used for accessing ArcGIS location services. API keys (legacy) have been replaced with API key credentials and can no longer be created.Learn more:

• June 2024: Legacy API keys in mature support. They can no longer be created or edited.

• June 2025: Legacy API keys in extended support. Retirement date June 2026 announced.

• June 27, 2026: Legacy API keys revoked. They can no longer be used to authenticate with ArcGIS services.

Advantages of using API key credentials

API key credentialsAPI key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential.Learn more are an ArcGIS content itemAn item, also known as a content item, is a resource stored in a portal such as a web map, hosted layer, style, script tool, file, or notebook.Learn more that can be used to create and manage API keys. These developer credentials offer several advantages over legacy API keys, including expanded access to ArcGIS services and enhanced management workflows.

Advantages of API key credentials include:

• Access to ArcGIS Location ServicesArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services.Learn more and secure content itemsAn item, also known as a content item, is a resource stored in a portal such as a web map, hosted layer, style, script tool, file, or notebook.Learn more
• Expanded access to spatial analysis servicesSpatial analysis services are services that perform geometry and statistical analyses on feature and raster data.Learn more and portalA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise.Learn more operations
• Configurable expiration date and referrer URLs
• Support for API key rotation with up to two API keys per credential
• ArcGIS EnterpriseArcGIS Enterprise is a GIS mapping, analytics, data hosting, and content management product that can be hosted on-premise or in a cloud infrastructure. It includes software, applications, tools, APIs, and services for users and developers.Learn more support

The following table compares the differences between API key credentialsAPI key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential.Learn more and legacy API keysAn API key (legacy) is a permanent access token created before June 2024 used for accessing ArcGIS location services. API keys (legacy) have been replaced with API key credentials and can no longer be created.Learn more:

How to switch to API key credentials

API key credentials can be used as a direct replacement for API keys (legacy). They are backwards compatible with all of the same privileges to access ArcGIS location services. The general steps to replace a legacy API key with API key credentials are:

1. Review the product and account requirements for API key authentication, and update your ArcGIS account if necessary.
2. Find the API key (legacy) you want to replace and go to its item pageAn item page is a web page in ArcGIS Online or the developer dashboard used to access and manage the properties for an item and the content it references such as a web map, hosted layer, or file.Learn more.
3. Review the scopes assigned to your legacy key.
4. Create a new API key credentialAPI key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential.Learn more in your portal under My content > New item.
5. Assign privilegesPrivileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS.Learn more to your credential to recreate the scopes of your API key (legacy).
6. Save the item. Copy the new API keyAn API key is a long-lived access token created using API key credentials. They are valid for up to one year and are typically embedded directly into client applications.Learn more to a secure location, as it is only visible once.
7. Replace the API key (legacy) in your application with the new API key you created.

API key (legacy) scopes

Legacy API keys were assigned scopes that controlled their access to ArcGIS location servicesArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services.Learn more. With API key credentials, the term scope has been replaced by the term privilege. PrivilegesPrivileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS.Learn more are assigned to API key credentials to control their access to location services and other secure resourcesA secure resource is any item or service in an ArcGIS that requires an ArcGIS account and authentication to access. Examples include ArcGIS Location Services, and items and data services in an ArcGIS portal.Learn more.

The following table lists all of the scopes for legacy API keys, and the equivalent privileges for API key credentials:

Tutorials