Tutorial: Rotate API keys

Learn how to rotate API keys in a deployed application to extend the lifetime of the application.

API key credentials
The item page of API key credentials in a portal

An API key is a long-lived access token used to authenticate requests to secure resources in applications. API keys are created and managed through API key credentials.

API key credentials can generate up to two valid API keys at a time, known as API key 1 and API key 2. The keys share identital privileges and item access, but their expiration dates are set individually. By staggering the expiration dates of the two API keys, API key credentials can be used to keep an application running indefinitely.

This tutorial explains how to rotate between an API key 1 and API key 2 in a deployed application. This workflow is necessary for applications in production environments, such as live websites or apps published to the app store. Using this method, API keys can be rotated in deployed applications without any application downtime.

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.

Find your API key credentials

Developer credentials are stored as an item in your portal. Go to the item page of your credentials to manage their settings.

  1. Go to Content > My content.

  2. Search for the developer credentials you created in the prerequisites step.

  3. Click on the developer credentials to go to its item page.

Check the API key 1 expiration date

API key credentials are used to manage up to two active API keys at a time. The expiration date of each API key is listed on the API key credentials item page.

  1. On the item page of your API key credentials, scroll down to Credentials > API keys.

  2. A partial record of each API key is listed along with its expiration date. Check the expiration date of your active API key 1.

    Partial API key 1

Generate an API key 2

When you are ready to rotate API keys, use the same API key credentials to generate an API key 2. This new key will share identical privileges and item access with API key 1, but has a unique expiration date.

  1. Go to Settings on the item page of your API key credentials.

  2. Under Application > API keys, click Generate a secondary API key.

    Generate a secondary API key
  3. Set an Expiration date for the key and click Generate API key.

    Expiration date picker

Copy the API key 2

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

    Copy the key
  2. Use the API key credentials item page to view a partial version of the new key, as well as its expiration date.

    Partial API keys

Deploy your application

After generating an API key 2 and pasting it into your application, your API key 1 can be safely deleted from the code base. You must deploy your application to production before the API key 1 can be invalidated.

  1. Deploy your application to production using your normal process. This process varies based on your chosen platform, programming language, and build system.

Invalidate the API key 1

Once your application has been deployed with a new API key, the previous API key is no longer required. Invalidate the key to prevent fraudulent usage.

  1. Go to Settings on the item page of your API key credentials.

  2. Under Application > API keys, find the API key you want to regenerate. Click Invalidate API key.

    Invalidate the API key
  3. Click Yes, invalidate API key.

    Invalidate key confirmation menu
  4. Your API key 1 has been invalidated. It will no longer function in applications or REST API requests. Your API key 2 will continue to function as normal.

    Partial API key 2

What's next?

Your application has been deployed using a new API key with an extended expiration date. When your API key 2's expiration date approaches, this same workflow can be applied again to keep the application running indefinitely. Once the API key 2 is about to expire, generate a new API key 1 and deploy your application again using the new key.

Next, expand the functionality of your application by completing one of the following tutorials:

Change the basemap layer

Switch a basemap layer from streets to satellite imagery.


Find places in a bounding box

Perform a text-based search to find places within a bounding box.


Query demographic data

Query demographic information for locations around the world with the GeoEnrichment service.


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