Rotate API keys

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 privileges and item access, but their expiration dates are set individually. By staggering the expiration dates of the two API keys, a single API key credential can be used to run an application indefinitely without downtime.

This tutorial explains how to rotate between an API key 1 and API key 2 in a deployed application. You will use arcgis-rest-developer-credentials module in ArcGIS REST JS to rotate API keys.

Prerequisites

Steps

Set up the project

This tutorial uses ArcGIS REST JS with Node.js to create a standalone console script. Set up the project directory and install the necessary packages.

1. Create a new directory using a code editor of your choice.

2. Set up a Node JS project and install the following packages using npm or yarn:

   • @esri/arcgis-rest-developer-credentials
   • @esri/arcgis-rest-request
   • dotenv

3. Create a main file called index.js. Import methods from ArcGIS REST JS.

   index.js

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   
   import { slotForKey, updateApiKey, invalidateApiKey } from "@esri/arcgis-rest-developer-credentials";
   import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
   

Set environment variables

1. Open your project directory in a code editor of your choice.

2. Create a new file named .env.

3. Add the following lines to your .env file and replace the placeholders with your actual credentials:

   • ARCGIS_USERNAME and ARCGIS_PASSWORD: Your ArcGIS account credentials.
   • PORTAL_URL (optional): If using ArcGIS Enterprise, update this with your portal's REST endpoint. Otherwise, you can omit this line.
   .env

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   
   ARCGIS_USERNAME="YOUR_ACCOUNT_USERNAME"
   ARCGIS_PASSWORD="YOUR_ACCOUNT_PASSWORD"
   PORTAL_URL="https://{machine.domain.com}/{webadaptor}/sharing/rest" # OPTIONAL - For Enterprise accounts only
   

4. Find the item ID of your API key credentials. This ID is found in the URL of the item page in your portal, and also returned when creating API keys programmatically with ArcGIS REST JS.

   .env

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   
   ARCGIS_USERNAME="YOUR_ACCOUNT_USERNAME"
   ARCGIS_PASSWORD="YOUR_ACCOUNT_PASSWORD"
   PORTAL_URL="https://{machine.domain.com}/{webadaptor}/sharing/rest" # OPTIONAL - For Enterprise accounts only
   
   API_KEY_ITEM_ID="YOUR_API_KEY_ITEM_ID"

5. Save the file.

Configure authentication

In this step, you will import the necessary classes from the ArcGIS REST JS library and load configuration variables from .env.

1. Access your environment variables from .env by importing dotenv/config.

   index.js

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   
   import { slotForKey, updateApiKey, invalidateApiKey } from "@esri/arcgis-rest-developer-credentials";
   import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
   
   import "dotenv/config";
   

2. Configure ArcGISIdentityManager with the username, password, and portal URL to set up authentication for the script.

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   import "dotenv/config";
   
   const authentication = await ArcGISIdentityManager.signIn({
     username: process.env.ARCGIS_USERNAME,
     password: process.env.ARCGIS_PASSWORD,
     portal: process.env.PORTAL_URL // OPTIONAL - For ArcGIS Enterprise only
   });
   

Generate an API key 2

In this step, you will locate your API key 1 and generate an API key 2 with a new expiration date.

1. Store your current API key in a variable and determine its slot number.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   let currentApiKey = "YOUR_API_KEY";
   
   const apiKeySlot = slotForKey(currentApiKey);
   
   

   Expand

2. Define an expiration date for the new API key, e.g. three days from now.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   let currentApiKey = "YOUR_API_KEY";
   
   const apiKeySlot = slotForKey(currentApiKey);
   
   const THREE_DAYS = new Date();
   THREE_DAYS.setDate(THREE_DAYS.getDate() + 3);
   THREE_DAYS.setHours(23, 59, 59, 999);
   
   

   Expand

3. Use updateApiKey to create a new API key with the specified expiration date.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   let currentApiKey = "YOUR_API_KEY";
   
   const apiKeySlot = slotForKey(currentApiKey);
   
   const THREE_DAYS = new Date();
   THREE_DAYS.setDate(THREE_DAYS.getDate() + 3);
   THREE_DAYS.setHours(23, 59, 59, 999);
   
   const result = await updateApiKey({
     itemId: process.env.API_KEY_ITEM_ID,
     authentication,
     generateToken1: apiKeySlot === 2,
     generateToken2: apiKeySlot === 1,
     apiToken1ExpirationDate: apiKeySlot === 2 ? THREE_DAYS : undefined,
     apiToken2ExpirationDate: apiKeySlot === 1 ? THREE_DAYS : undefined
   });
   
   

   Expand

4. Retrieve the newly generated API key and use it to update currentApiKey. Then, print it to the console.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   let currentApiKey = "YOUR_API_KEY";
   
   const apiKeySlot = slotForKey(currentApiKey);
   
   const THREE_DAYS = new Date();
   THREE_DAYS.setDate(THREE_DAYS.getDate() + 3);
   THREE_DAYS.setHours(23, 59, 59, 999);
   
   const result = await updateApiKey({
     itemId: process.env.API_KEY_ITEM_ID,
     authentication,
     generateToken1: apiKeySlot === 2,
     generateToken2: apiKeySlot === 1,
     apiToken1ExpirationDate: apiKeySlot === 2 ? THREE_DAYS : undefined,
     apiToken2ExpirationDate: apiKeySlot === 1 ? THREE_DAYS : undefined
   });
   
   const newApiKey = apiKeySlot === 2 ? result.accessToken1 : result.accessToken2;
   currentApiKey = newApiKey;
   
   console.log(`\nNew API key in slot ${apiKeySlot === 1 ? 2 : 1} created: ${newApiKey}`);
   

   Expand

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

After 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. Call invalidateApiKey to revoke the previous API key. If the operation is successful, log the result to confirm the key has been invalidated.
   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   const invalidateResponse = await invalidateApiKey({
     itemId: process.env.API_KEY_ITEM_ID,
     authentication,
     apiKey: currentApiKey
   });
   
   if (invalidateResponse.success) {
     console.log(`\nOld key in slot ${apiKeySlot} invalidated.`);
   }

What's next?