Introduction to API key authentication

API key authentication is a type of authentication that uses long-lived access tokens embedded directly into an application to authenticate requests to location services and private items. The access tokens are called API keys and managed through API key credentials. It is the easiest type of authentication to set up, and is the recommended type of authentication for applications that only access location services.

You can use API key authentication to:

  • Create public applications that do not require users to sign in.
  • Build applications that only need to access location services or private items such as hosted layers and data services.
  • Quickly and easily get access tokens.
  • Embed an access token directly into apps that remains valid for up to 1 year.
  • Access secure resources with the privileges of your ArcGIS account.

How API key authentication works

API key overview
The API key authentication workflow

API key authentication requires an API key, a type of access token created through API key credentials. API key credentials are an item created in your portal that are used to create API keys and manage their privileges.

The general steps to implement API key authentication are:

  1. Create API key credentials to get an API key.

  2. Paste the API key access token into your application.

  3. Your application uses the API key as an access token to access secure resources.

Your API key must have the correct privileges 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 credentials.

API key credentials

API key credentials are an item in your portal used to create and manage API keys. You can manage the settings of API key credentials on their item page to generate up to two API keys, define their privileges 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 item for each application. API key credentials are used to configure the privileges of an API key, which grant access to specific services, items, and operations in ArcGIS.

Hybrid authentication

In ArcGIS APIs, the AuthenticationManager and IdentityManager classes automatically implement a hybrid approach when using both API key authentication and user authentication.

Applications can use both API keys and user authentication, utilizing their API key for location services while the user is signed out and then switching to an access token from user authentication when the user signs in.


Resources and functionality

The following table is an overview of the resources and the functionality available when implementing each type of authentication:

API key authenticationUser authenticationApp authentication
Location services
Data services (Item access)
Spatial analysis services
Portal service (General privileges)
Portal service (Admin privileges)
Full supportPartial supportNo support

    Account types

    API key authentication is only available to ArcGIS Location Platform accounts and ArcGIS Online accounts. API key authentication is not currently available for ArcGIS Enterprise. API key authentication is not available with any other ArcGIS account type such as Public, Education, Personal Use, and others.

    ArcGIS Online accounts must have a role with the "Generate API key" privilege to use API key authentication.

    Max keys

    There is a 100 key limit for ArcGIS Location Platform accounts and a 100 key limit for all accounts combined in an ArcGIS Online organization. This limit can be adjusted if you need more than 100 API keys. Contact Esri Technical Support or your local distributor.

    API keys (Legacy)

    All API keys created before June 2024 are known as API keys (Legacy). These API keys still function, but can no longer be created. To create new API keys, you need to create API key credentials in your portal.

    The new API key credentials differ from API keys (legacy) in the following ways:

    • Access tokens from API key credentials are long-lived (up to one year) and not permanent.
    • API key credentials can have up to two associated access tokens.
    • API key credentials support expiration and rotation.
    • Access tokens from API key credentials need to be regenerated when the token's expiration date or privileges are changed.


    Create an API key

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

    Manage API key credentials

    Manage previously created API key credentials to regenerate, edit privileges, and edit item access of API keys.

    Migrate API keys (legacy) to API key credentials

    Migrate from an API key (legacy) created before June 2024 to an API key from API key credentials.

    API support

    API key authentication
    ArcGIS Maps SDK for JavaScript
    ArcGIS Maps SDK for .NET
    ArcGIS Maps SDK for Kotlin
    ArcGIS Maps SDK for Swift
    ArcGIS Maps SDK for Java
    ArcGIS Maps SDK for Qt
    ArcGIS API for Python
    Esri Leaflet
    MapLibre GL JS
    Full supportPartial supportNo support

      Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.