Create an API key

An API key is a long-lived access token that authorizes your application to access secure services, content, and functionality in ArcGIS.

This tutorial shows you how to use the arcgis-rest-developer-credentials module in ArcGIS REST JS to programmatically create API key credentials and do the following:

• Generate long-lived API keys and save them in your application.
• Configure privileges to allow your API keys to access ArcGIS services, content, and functionality.
• Set the expiration date of an API key.
• Manage 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
   • @esri/arcgis-rest-portal
   • 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
   
   import { createApiKey } from "@esri/arcgis-rest-developer-credentials";
   import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
   import { moveItem, getSelf } from "@esri/arcgis-rest-portal";
   

Set environment variables

Set up environment variables to store information about your ArcGIS account.

1. Create a new file named .env.

2. Add the following variables to the file. Replace "YOUR_ACCOUNT_USERNAME" and "YOUR_ACCOUNT_PASSWORD" with your ArcGIS account credentials. If you are using ArcGIS Enterprise, update "PORTAL_URL" with your portal's REST endpoint. Otherwise, you can omit this field.

   .env

   Use dark colors for code blocks

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

3. Save the file.

Configure authentication

1. Load the environment variables by importing dotenv/config. Configure ArcGISIdentityManager with the username, password, and portal URL to set up authentication for the script.

   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
   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
   });
   

2. Call getSelf to get the URL of your organization, which will be needed in a later step.

   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
   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
   });
   
   const orgUrl = await getSelf({ authentication: authentication });
   
   

Create an API key credential

Generate an API key programmatically using ArcGIS REST JS. You will define key properties such as its title, description, and tags, then set privileges and an expiration date.

1. Using createApiKey, generate a new API key credential with the following properties:

   • Title: API key ${Math.floor(Date.now() / 1000)}
   • Description: API Key generated with ArcGIS REST JS with spatial analysis and basemap privileges
   • Tags: api key, basemaps, spatial analysis, authentication
   • Generate token 1: true
   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
   const newKey = await createApiKey({
     title: `API key ${Math.floor(Date.now() / 1000)}`,
     description: "API Key generated with ArcGIS REST JS with spatial analysis and basemap privileges",
     tags: ["api key", "basemaps", "spatial analysis", "authentication"],
   
     generateToken1: true,
   
     authentication: authentication
   });
   
   

2. Set the privileges for the API key credential. The specific privileges required by your key depend on your use case. To view all available privileges, go to Privileges.

   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
   const newKey = await createApiKey({
     title: `API key ${Math.floor(Date.now() / 1000)}`,
     description: "API Key generated with ArcGIS REST JS with spatial analysis and basemap privileges",
     tags: ["api key", "basemaps", "spatial analysis", "authentication"],
   
     privileges: [
       "premium:user:spatialanalysis",
       "premium:user:basemaps" // Not available for ArcGIS Enterprise
     ],
   
     generateToken1: true,
   
     authentication: authentication
   });
   
   

3. Specify the expiration date for the API key you are generating.

   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
   const newKey = await createApiKey({
     title: `API key ${Math.floor(Date.now() / 1000)}`,
     description: "API Key generated with ArcGIS REST JS with spatial analysis and basemap privileges",
     tags: ["api key", "basemaps", "spatial analysis", "authentication"],
   
     privileges: [
       "premium:user:spatialanalysis",
       "premium:user:basemaps" // Not available for ArcGIS Enterprise
     ],
   
     generateToken1: true,
   
     apiToken1ExpirationDate: new Date(Date.now() + 1000 * 60 * 60 * 24 * 30), // 30 days
   
     authentication: authentication
   });
   
   

4. Once the operation is complete, an API key credential will be created as an item in your portal. You can access the item ID and other properties of the object, including all API keys associated with the item. The API key 1 generated here should be stored for use in other requests.

   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
   const newKey = await createApiKey({
     title: `API key ${Math.floor(Date.now() / 1000)}`,
     description: "API Key generated with ArcGIS REST JS with spatial analysis and basemap privileges",
     tags: ["api key", "basemaps", "spatial analysis", "authentication"],
   
     privileges: [
       "premium:user:spatialanalysis",
       "premium:user:basemaps" // Not available for ArcGIS Enterprise
     ],
   
     generateToken1: true,
   
     apiToken1ExpirationDate: new Date(Date.now() + 1000 * 60 * 60 * 24 * 30), // 30 days
   
     authentication: authentication
   });
   
   console.log(`\nNew API key created: ${newKey.accessToken1}`);
   console.log(`\nView item: https://${orgUrl.urlKey}.maps.arcgis.com/home/item.html?id=${newKey.itemId}`);
   

Manage your credential (optional)

To keep your credentials organized, it is a best practice to store all API key credentials in a designated folder. You can move the credential to a specific folder in your portal using moveItem.

1. Use the following code to move the newly created API key into a folder dedicated to storing API key credentials.

   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
   const moved = await moveItem({
     itemId: newKey.itemId,
     folderId: "YOUR_FOLDER_ID",
     authentication: authentication
   });
   
   console.log(`\nItem moved ${JSON.stringify(moved)}`);

2. You can also use updateApiKey to modify the API key credential, such as:

   • Reassigning privileges
   • Assigning item access using portal:app:access:item:{ITEM_ID}
   • Changing the API key expiration date
   • Generating a secondary access token

Run the app

Run the app.

After running the script, you should see the generated access token printed in the console, along with a URL to view the API key credential item in your portal.

What's next?