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

Sign in to your portal

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

  1. Sign in to your portal 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.

  1. Go to Content > My content.
  2. 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. API key legacy item
  3. Under Credentials, click Manage.
  4. In API key (legacy), scroll down to the Location services section.
  5. 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

  1. In your portal, click Content > My content > New item.

  2. Click Developer credentials > API key credentials and click Next.

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.

  1. 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.

    Expiration date selector
  2. 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.

    Referrer selector
  3. Click Next.

Select privileges

You can configure the settings of API key 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.

  1. In the Create developer credentials > Privileges window, browse the available privileges.

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

    Legacy scopeEquivalent privilegePrivilege label
    Basemapspremium:user:basemapsBasemap styles service
    Placespremium:user:placesPlaces service
    Geocoding (stored)premium:user:geocode:storedGeocode (stored)
    Geocoding (not stored)premium:user:geocode:temporaryGeocode (not stored)
    Routingpremium:user:networkanalysis:routingSimple routing
    Optimized routingpremium:user:networkanalysis:optimizedroutingOptimized routing
    Closest facilitypremium:user:networkanalysis:closestfacilityClosest facility
    Service areapremium:user:networkanalysis:serviceareaService area
    Location allocationpremium:user:networkanalysis:locationallocationLocation allocation
    Multi-vehicle routingpremium:user:networkanalysis:vehicleroutingMulti-vehicle routing
    Origin/destination cost matrixpremium:user:networkanalysis:origindestinationcostmatrixOrigin/destination cost matrix
    GeoEnrichmentpremium:user:geoenrichmentGeoEnrichment service
  2. Select the location service privileges that mimic the original 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.

  1. If your token does not require item access, click Skip.

  2. In the Grant item access window, click Browse items.

    Item access button
  3. Select the items you want to grant access to. You can select up to 100 items in this menu.

  4. Click Add items.

Save the item

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

  1. 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.
    API key credential details

    Click Next.

  2. In the Summary window, review the properties, privileges, and item access you have set. Click Next.

Copy the API key

  1. 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.

    Generate the key
  2. Click Next.

  3. Copy the API key from the window that appears and paste it into your application.

    Copy the key

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.

  1. Go to Content > My content.
  2. 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.
  3. Click on the Settings tab.
  4. 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:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.