Tutorial: Rotate API keys

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

An API key is a long-lived access tokenAn 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 used to authenticate requests to 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 in applications. API keys are created and managed through 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.

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 identical 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 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. In your web browser, go to your ArcGIS Enterprise portal and sign in to your portal with your ArcGIS Enterprise account.

Find your API key credentials

Developer credentialsDeveloper credentials are a type of item in a portal that contains parameters for authentication. There are two types of developer credentials: API key credentials and OAuth credentials.Learn more are stored as an 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 in your portal. Go to the 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 of your credentials to manage their settings.

1. Go to Content > My content.

2. Search for the developer credentialsDeveloper credentials are a type of item in a portal that contains parameters for authentication. There are two types of developer credentials: API key credentials and OAuth credentials.Learn more you created in the prerequisites step.

3. Click on the developer credentials to 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.

Check the API key 1 expiration date

API key credentials are used to manage up to two active API keysAn 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 at a time. The expiration date of each API key is listed on the API key credentials 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.

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

   

Generate an API key 2

When you are ready to rotate API keys, use the same 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 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. Under Application > API keys, click Generate a secondary API key.

   

2. Set an Expiration date for the key and click Generate API key.

   

Copy the API key 2

1. Copy the 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 from the window that appears and paste it into your application.

   

2. Use the API key credentials 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 to view a partial version of the new key, as well as its expiration date.

   

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. Under Application > API keys, find the API key you want to regenerate. Click Invalidate API key.

   

2. Click Yes, invalidate API key.

   

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

   

What's next?

Your application has been deployed using a 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 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.

Learn how to perform other management tasks for your API key credentials in the following tutorials: