API key credentials | Documentation

Learn about API key credentials with ArcGIS Enterprise.

API key credentials are 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 used to create and manage 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. You can manage the settings of API key credentials to generate up to two API keys and define their privileges and expiration date. API key credentials can also be used to regenerate or invalidate existing API keys.

Creating API key credentials

Prerequisites

API key credentials can be created using an ArcGIS Enterprise account. The account must have a user type of Creator or higher, as well as a custom role with these 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:

General privileges > Content > Assign privileges to OAuth 2.0 applications
General privileges > Content > Generate API keys

In addition to the account requirements, your ArcGIS Enterprise portal must be version 11.4 or greater. To learn more, go to the Product and account requirements.

Steps

The steps to create API key credentials are described in the Create an API key tutorial:

Create an API key

Create and configure API key credentials to get a long-lived API key access token.

ArcGIS portal REST JS

Privileges

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 include a privilegePrivileges 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 selector that can authorize access to secure ArcGIS servicesA service, also known as an ArcGIS service, is software that supports an ArcGIS REST API and provides geospatial functionality or data. A service can be hosted by Esri or in ArcGIS Enterprise.Learn more. Once privileges are configured using the selector, the resulting 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 will be authorized to access the specified services and perform operations.

The privilege selector for developer credentials in ArcGIS Enterprise.

The privileges available to API key credentials with an ArcGIS Enterprise account generally include:

General portalA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise.Learn more operations, such as creating and managing items and groups.
Administrative portalA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise.Learn more operations, such as inviting members, generating reports, and managing organization settings.
Spatial analysis servicesSpatial analysis services are services that perform geometry and statistical analyses on feature and raster data.Learn more for performing feature and raster analysis operations.

The exact privileges available depend on the user type and role of the ArcGIS Enterprise account that created the credentials.

Edit privileges

You can edit the privileges of your API key credentials to adjust the authorization level of your API keys.

Go to Settings 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 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.
Under Application > Credentials, click the Edit button. In the warning that appears, click Continue. If this option is not available to your account, please refer to the Product and account requirements for API key authentication.
Select a type of application that your key will be used in.
Select No item access if you do not want to grant access to any items, or select Grant access to specific items if you want to grant access to certain items in your portal. Then, click Next.
Select new privileges for your API key credentials using the privileges window. To view a list of all available privileges, go to Privileges.
Click Save to close the window. Then, click the Save button again under Application to update your developer credential.

Item access privileges

The item access menu for developer credentials

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 also include an item access menu used to allow access to specific itemsAn 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 a portalArcGIS portal, also known as a portal, is a website with applications and tools that can be used to create, manage, access, and share geospatial content and data. It supports security and authentication, developer credentials, content and data service management, user and group management, and site administration. A portal can be hosted in Esri's infrastructure or your own infrastructure.Learn more. The resulting access tokensAn 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 will be authorized to access any items you specify in this menu.

The items available in this menu include all of the items owned by your account with a sharing levelSharing level is the security setting assigned to an item in a portal that controls which users can access the resource. The sharing levels are Owner, Organization, Groups, and Everyone.Learn more of Private, Group, or Organization. API key credentials can be configured to access a maximum of 100 items.

Edit item access

You can edit the items that your API key credentials are authorized to access.

Go to Settings 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 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.
Under Application > Credentials, click the Edit button. In the warning that appears, click Continue. If this option is not available to your account, please refer to the Product and account requirements for API key authentication.
In the Item access window, select Grant access to specific items to grant access to specific items in your portal.
Select items to grant your API key credentials access to.
Click Save to close the window. Then, click the Save button again under Application to update your developer credential.

Referrers

The referrers field for developer credentials

A referrer is an HTTP header field used to identify the client requesting a server resource. This functions as a security measure, allowing applications to confirm their client's identity. When 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 have a specific HTTP referer header set, services can confirm that an incoming request's referrer matches one of the valid referrers assigned to that access token.

Specific domains can be provided or you can use wildcard characters (*) in the subdomain of your allowed referrer. For example https://*.your-app.com will allow the access token to be used on both https://dev.your-app.com and https://your-app.com. While it is also possible to restrict access token use to specific paths (https://your-app.com/page), we do not recommend this method because browsers may remove the path due to privacy concerns.

Manage API keys

Item page for an API key credentials item. The item is titled "My API key credentials (for a public app)" and has a type of "Application", with a badge that says "API key credentials".

API key credentials in a portal.

API key credentials are used to manage 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, a type of 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. You can manage the settings of your API keys from 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.

The following management actions are supported for API keys:

Generate a secondary API key

You can generate a secondary 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 in the same credentials with identical privileges and a new expiration date. The first API key will remain valid. This action is commonly used when Rotating API keys in your application.

Go to Settings 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.
Under Application > API keys, click Generate a secondary API key.
Set an Expiration date for the key and click Generate API key.
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.

Regenerate an API key

If you lose access to an API key, you can regenerate it with a new expiration date. This will invalidate the previous key.

Go to Settings 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.
Under Application > API keys, find the API key you want to regenerate. Click Regenerate API key.
Click Confirm expiration date and set a new expiration date if desired.
Click Yes, regenerate API key. 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.

Invalidate an API key

You can invalidate an API key so that it no longer functions in applications. If your API key gets stolen, it should be invalidated to avoid fraudulent charges to your subscriptionAn ArcGIS subscription is a free or paid plan that defines the capabilities of an ArcGIS account and the method of billing for the consumption of location services.Learn more.

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

Rotate API keys

Up to two 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 can be created in each set of 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. The two API keys have individual expiration dates, but share the same 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 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 access defined by the credentials.

Creating two API keys in one set of credentials allows you to seamlessly rotate keys in your deployed application. When an API key is about to expire, you can generate a second API key and replace it in your application without the app going offline. The high-level workflow for rotating API keys is as follows:

Sign in to your portalArcGIS portal, also known as a portal, is a website with applications and tools that can be used to create, manage, access, and share geospatial content and data. It supports security and authentication, developer credentials, content and data service management, user and group management, and site administration. A portal can be hosted in Esri's infrastructure or your own infrastructure.Learn more to view your 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.
Check the expiration date of your API key 1. API keys should be rotated in your applications when they are close to their expiration date.
When your API key 1's expiration date is approaching, go to Settings > Application in your API key credentials and click Generate a secondary API key.
Set the Expiration date of your API key 2 and click Generate API key.
Copy the API key 2 and paste it into your application.
Deploy your application using the new API key 2 before your API key 1 expires.

Usage tracking

All services and content accessed with 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 are tracked. You can monitor the usage of credentials in order to view the consumption of services and the billing amount.

ArcGIS Enterprise developers use their portalArcGIS portal, also known as a portal, is a website with applications and tools that can be used to create, manage, access, and share geospatial content and data. It supports security and authentication, developer credentials, content and data service management, user and group management, and site administration. A portal can be hosted in Esri's infrastructure or your own infrastructure.Learn more to monitor service usage. In ArcGIS Enterprise, individual usage monitoring for 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 are not available. To monitor the total service usage within your organization, you can generate a usage report.