Introduction to API key authentication

API key authentication is a type of authentication that uses long-lived 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 embedded directly into an application to authenticate requests to access 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 and 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. The access tokens are called 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 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 authentication is the easiest type of authentication to use, but it is not sufficient to protect confidential information. It is recommended only if you are an ArcGIS developer working exclusively with public information and basic location servicesArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services.Learn more. If you are building applications that access private 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 or hosted data servicesData services, also known as hosted data services, are services created dynamically to store and provide access to your data in ArcGIS. Examples are feature services, vector tile services, map tile services, image services, and scene services.Learn more that contain confidential or sensitive data, you should use a stronger authentication method provided by ArcGIS Online or ArcGIS Enterprise. These are user authentication and app authentication.

You can use API key authentication to:

• Create public applicationsA public application is an application that allows anonymous access without requiring users to sign in with an ArcGIS account. It supports API key or app authentication.Learn more that do not require users to sign in.
• Build applications that access location servicesArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services.Learn more and private items such as hosted layersA hosted layer is an item in a portal that contains the properties and settings for a hosted data service or a layer in a hosted data service.Learn more and data servicesData services, also known as hosted data services, are services created dynamically to store and provide access to your data in ArcGIS. Examples are feature services, vector tile services, map tile services, image services, and scene services.Learn more.
• Create personal automation scripts that access the portal serviceA 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 and spatial analysis servicesSpatial analysis services are services that perform geometry and statistical analyses on feature and raster data.Learn more.
• Quickly and easily generate 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.
• Embed an 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 directly into apps that remains valid for up to 1 year.
• Access secure resources with the privileges of your ArcGIS accountAn ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription.Learn more.

How API key authentication works

API key authentication requires creating and configuring 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 so you can get an 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. 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. 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 created in 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 that are used to create API keys and manage their privileges.

The general steps to implement API key authentication are:

1. Create 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 get an API key.

2. Paste 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 access token into your application.

3. Your application uses the API key as an 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 to access 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.

Your API key must have the correct 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 to access secure resources. It is also recommended that you set referrer URLs in order to enhance the security of the token. These properties are managed through setting page 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.

API key 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 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 in 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 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 on their 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 generate up to two API keys, define their 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 set their expiration dates. API key credentials can also be used to regenerate or invalidate existing API keys.

API key authentication requires API key credentials. The most common pattern is to create a new API key credentials 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 for each application. API key credentials are used to configure the 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 of an API key, which grant access to specific services, items, and operations in ArcGIS.

Tutorials

Hybrid authentication

In ArcGIS APIsAn ArcGIS API is a web, native, game engine, or scripting API that has advanced mapping and spatial analysis capabilities and can be used to access ArcGIS services. ArcGIS APIs are designed to work optimally with the ArcGIS system and provide the most advanced GIS features and the highest performance possible.Learn more, the AuthenticationManager and IdentityManager classes automatically implement a hybrid approach when using both API key authenticationAPI key authentication is a type of authentication that uses an API key to authenticate requests to ArcGIS services and secure portal items.Learn more and user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more.

Applications can use both API keys and user authentication, utilizing their API key to access services while the user is signed out and then switching to an 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 from user authentication when the user signs in.

Product and account requirements

API key authentication is available with ArcGIS Location PlatformArcGIS Location Platform, formerly known as ArcGIS Platform, is a Platform as a Service (PaaS) product that gives developers access to location services, APIs, and tools to build mapping and spatial analysis applications. It is subscription-based and requires an ArcGIS Location Platform account.Learn more, ArcGIS OnlineArcGIS Online is a GIS mapping, analytics, data hosting, and content management software as a service (SaaS) product. It includes applications, tools, APIs, and location services for users and developers. It is subscription-based and requires an ArcGIS Online account.Learn more, and ArcGIS EnterpriseArcGIS Enterprise is a GIS mapping, analytics, data hosting, and content management product that can be hosted on-premise or in a cloud infrastructure. It includes software, applications, tools, APIs, and services for users and developers.Learn more. This section outlines the account requirements for each major product type.

ArcGIS Location Platform

All ArcGIS Location Platform accounts have the correct privileges to manage API key authentication by default.

ArcGIS Online

API key authentication requires an ArcGIS Online account with a user type of Creator or higher. The account must also have these additional 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

Your organization administrator can grant you these privileges using a custom role. Learn more in the FAQ.

ArcGIS Online Trial: API key authentication is not available in ArcGIS Online Trial subscriptions.

ArcGIS for Personal Use: API key authentication is not available in ArcGIS Online subscriptions purchased through ArcGIS for Personal Use.

ArcGIS Hub: API key authentication is not available with for accounts with the Hub Community Member user type. This includes community administrators.

ArcGIS Enterprise

API key authentication requires an ArcGIS Enterprise account with a user type of Creator or higher. The account must also have these additional 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

Your organization administrator can grant you these privileges using a custom role. Learn more in the FAQ.

Version requirement: API key authentication is only available with ArcGIS EnterpriseArcGIS Enterprise is a GIS mapping, analytics, data hosting, and content management product that can be hosted on-premise or in a cloud infrastructure. It includes software, applications, tools, APIs, and services for users and developers.Learn more version 11.4 or greater. To learn more, go to Developer credentials for ArcGIS Enterprise.

Limitations

Location services

ArcGIS Enterprise limitations: API key authentication cannot be used to access ArcGIS Location ServicesArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services.Learn more with ArcGIS Enterprise. However, API keys can still be used to access secure 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 your Enterprise portal, such as locators (geocoding services)A locator is an ArcGIS dataset that stores address information and the rules for translating descriptions of places (such as street addresses or place names) into spatial data that can be displayed on a map.Learn more and hosted data servicesData services, also known as hosted data services, are services created dynamically to store and provide access to your data in ArcGIS. Examples are feature services, vector tile services, map tile services, image services, and scene services.Learn more.

API key credentials

Creating credentials: There is no limit to the number of API key credentials and API keys you can create.

Accessing items: An API key credential can be configured to access a maximum of 100 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 you own.

Viewing API keys: The value of an 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 can only be viewed when the API key is first generated. After a key has been created, its full value is no longer accessible and is not stored in ArcGIS. If you lose the value of an API key, you have to invalidate it and generate a new key using the 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 item page.

Changing properties: Editing any of the 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, item access privileges, or the expiration date of API key credentials will invalidate all API keys generated from that credential. New keys can be generated in the Settings section of the API key credentials item page.

API keys (legacy)

Prior to June 2024, API key authentication used API keys (legacy)An API key (legacy) is a permanent access token created before June 2024 used for accessing ArcGIS location services. API keys (legacy) have been replaced with API key credentials and can no longer be created.Learn more. These API keys still function, but can no longer be created or modified and will soon be retired. All new API keys must be created using 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.

Service support

The following table provides an overview of the functionality available with each type of authentication:

API support