Migrate API keys (legacy) to API key credentials

API keys (legacy) are permanent access tokens created before June 2024. They can no longer be created or managed, and have been replaced by API key credentials. All developers should replace their existing API keys (legacy) with new API keys from API key credentials.

This tutorial shows how to migrate your application from an API key (legacy) to an API key from API key credentials and preserve the same privileges and item access.

Prerequisites

Steps

You use your portal to create and manage items, including API key credentials.

Access your portal by navigating to ArcGIS.com.
Sign in with your ArcGIS account.

Check the scopes of your API key (legacy)

API keys (legacy) can only be scoped to access location services. These capabilities and more are also available through API key credentials. Use your portal to check the service scopes of your API key (legacy) to create a new set of credentials with equivalent capabilities.

Go to Content > My content.
Click on the API key (legacy) item you want to replace. The item should have the label API key (legacy). You will then be redirected to the item page of your API key (legacy) item.
Under Credentials, click Manage.
In API key (legacy), scroll down to the Location services section.
Write down the selected scopes under Required service and Available services. These scopes will be replicated in your API key credentials using privileges.

Create API key credentials

In your portal, click Content > My content > New item.
Click Developer credentials > API key credentials and click Next.

ArcGIS Online accounts:
If you have an ArcGIS Online account, your account must have administrator access or a custom role with the Generate API keys privilege. To learn more, go to Limitations.

Set the expiration date and referrers

API key credentials generate long-lived access tokens called API keys. API keys are valid for up to one year, and their expiration date is set when they are generated. You can also set referrers on an API key, which restrict the key to only be usable from authorized domains.

In the Create developer credentials window, click on the Expiration date field. Set the expiration date of the access token to one month from today's date.
Set the Referrers field to the web domains you would like to restrict the access token to. This is highly recommended for security purposes. To learn more about referrers, go to API key credentials.
Click Next.

Select privileges

You use developer credentials to configure the privileges of access tokens. For an access token to work in your application, it needs to have the correct privileges to access the content and services your app is using. Select the privileges you require to apply them to your API key access token.

In the Create developer credentials > Privileges window, browse the available privileges.
Tip
If a privilege is not visible in your developer credentials, it may not be available for the following reasons:
- Your account does not have the correct user type or roles.
- You have the wrong type of subscription. Some privileges are only available to ArcGIS Location Platform users, and some are only available to ArcGIS Online users.
- You do not have pay-as-you-go enabled in your ArcGIS Location Platform account.
- You are using a type of authentication that does not support the privilege you require. To learn more, go to Types of authentication.

Expand the tables below to view the equivalent privileges for each location service scope of API keys (legacy).

Legacy scope	Equivalent privilege	Privilege label
Basemaps	`premium:user:basemaps`	Basemap styles service
Places	`premium:user:places`	Places service
Geocoding (stored)	`premium:user:geocode:stored`	Geocode (stored)
Geocoding (not stored)	`premium:user:geocode:temporary`	Geocode (not stored)
Routing	`premium:user:networkanalysis:routing`	Simple routing
Optimized routing	`premium:user:networkanalysis:optimizedrouting`	Optimized routing
Closest facility	`premium:user:networkanalysis:closestfacility`	Closest facility
Service area	`premium:user:networkanalysis:servicearea`	Service area
Location allocation	`premium:user:networkanalysis:locationallocation`	Location allocation
Multi-vehicle routing	`premium:user:networkanalysis:vehiclerouting`	Multi-vehicle routing
Origin/destination cost matrix	`premium:user:networkanalysis:origindestinationcostmatrix`	Origin/destination cost matrix
GeoEnrichment	`premium:user:geoenrichment`	GeoEnrichment service

Legacy scope	Equivalent privilege	Privilege label
Basemaps	`premium:user:basemaps`	Basemap styles service (This privilege cannot be disabled)
Places	`premium:user:places`	Places service
Geocoding (stored)	`premium:user:geocode`	Geocode
Geocoding (not stored)	`premium:user:geocode`	Geocode
Routing	`premium:user:networkanalysis`	Routing
Optimized routing	`premium:user:networkanalysis`	Routing
Closest facility	`premium:user:networkanalysis`	Routing
Service area	`premium:user:networkanalysis`	Routing
Location allocation	`premium:user:networkanalysis`	Routing
Multi-vehicle routing	`premium:user:networkanalysis`	Routing
Origin/destination cost matrix	`premium:user:networkanalysis`	Routing
GeoEnrichment	`premium:user:geoenrichment`	GeoEnrichment service

Select the correct location service privileges to mimic the service scopes of your API key (legacy) and click Next.

Select items (optional)

If your application will require access to specific private items, you will need to configure your developer credentials to access them. The Item access menu allows you to browse your portal's content and grant your key fine-grained access to specific items.

If your token does not require item access, click Skip.
In the Grant item access window, click Browse items.
Select the items you want to grant access to. You can select up to 100 items in this menu.

Warning
Certain privileges such as features:user:edit will grant global access to all items associated with your account. Setting fine-grained item access using this menu will override any global privileges you have set.
Click Add items.

Save the item

After configuring the properties of your API key credentials, you can save the credentials as a new item.

In the Create developer credentials window, set the following properties:
- Title: My API key credentials
- Folder: Developer credentials (Create a new folder)
- Tags: Add tags related to the privileges of the credentials.
- Description: Describe the application that these developer credentials will be used in.
Click Next.
In the Summary window, review the properties, privileges, and item access you have set. Click Next.

Copy the API key

In the Create developer credentials > Generate API key window, select Generate the API key and go to item details page. I am ready to copy and save the key.
Click Next.
Copy the API key from the window that appears and paste it into your application.

Attention
This is the only time you will be able to access the value of your API key access token. You will not be able to view it again. To get a new key, you need to regenerate one using the API key credentials item page.

Delete the API key (legacy)

Once you replace your API key (legacy) in your application with your new API key, you can safely delete the API key (legacy) item.

Go to Content > My content.
Click on the API key (legacy) item you want to delete. You will then be redirected to the item page of your API key (legacy) item.
Click on the Settings tab.
In General, click Delete Item > Delete.

What's next?

Learn how to use your API key to access secure ArcGIS resources in the following guides:

Mapping and location services

Portal and data services

Low-code/no-code app builders

Spatial analysis services

Offline mapping apps