API keys (legacy) are permanent access tokens created before June 2024 that were used for accessing ArcGIS location services. Legacy API keys can no longer be created, and must be replaced with API keys generated from API key credentials.
This page contains essential information for updating your applications:
Retirement timeline
This timeline shows the lifecycle and deprecation of API keys (legacy):
-
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 2026: Legacy API keys retired. They can no longer be used to authenticate with ArcGIS services.
Advantages of using API key credentials
API key credentials are an ArcGIS content item 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 Services and secure content items
- Expanded access to spatial analysis services and portal operations
- Configurable expiration date and referrer URLs
- Support for API key rotation with up to two API keys per credential
- ArcGIS Enterprise support
The following table compares the differences between API key credentials and legacy API keys:
| API key credentials | API key (legacy) | |
|---|---|---|
| Max number of keys (ArcGIS Location Platform account) | No limit | 100 keys |
| Max number of keys (ArcGIS Online, cumulative across all organization members) | No limit | 100 keys |
| Supported ArcGIS services | ArcGIS Location Services, Spatial analysis services, Portal service | ArcGIS Location Services |
| Item access privileges | Supported for all account types | Supported for ArcGIS Location Platform only |
| Max number of item access privileges | 100 items per credential | 100 items per key |
| API key expiration date | Configurable (Duration of up to one year) | Not configurable |
| API key rotation (?) | Supported | Not supported |
| ArcGIS Enterprise support | Supported in ArcGIS Enterprise >= 11.4 | Not supported |
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:
- Review the product and account requirements for API key authentication, and update your ArcGIS account if necessary.
- Find the API key (legacy) you want to replace and go to its item page.
- Review the scopes assigned to your legacy key.
- Create a new API key credential in your portal under My content > New item.
- Assign privileges to your credential to recreate the scopes of your API key (legacy).
- Save the item. Copy the new API key to a secure location, as it is only visible once.
- 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 services. With API key credentials, the term scope has been replaced by the term privilege. Privileges are assigned to API key credentials to control their access to location services and other secure resources.
The following table lists all of the scopes for legacy API keys, and the equivalent privileges for API key credentials:
Tutorials
Update to API key credentials
Migrate from an API key (legacy) created before June 2024 to an API key from API key credentials.
Create an API key
Create and configure API key credentials to get a long-lived API key access token.
Manage API key credentials
Manage previously created API key credentials to regenerate, edit privileges, and edit item access of API keys.