API key authentication

An application programming interface key (API key) is a permanent access token that defines the scope and permission for granting applications access to ArcGIS location services and private content items for data services.

How API keys work

API keys provide an easy way to control and manage how your applications access ArcGIS resources. To start using API keys, use your developer dashboard. The dashboard allows you to add, delete, scope, and monitor the usage of location services for all API keys. If you have an ArcGIS Developer account, a default API key was created for you when you signed up. If you have an ArcGIS Online account, you need to create a new API key. Once you have an API key, you can use it in an application. The most common pattern is to create one API for each application. This makes it possible to monitor the location service usage for each application you deploy.

The general steps to use API keys are to:

  1. Create and configure an API key in your developer dashboard.

  2. Use the API key in your application.

  3. Access location services.

API key overview
Figure 1: The typical workflow for creating and using API keys.

How to use API keys in apps

After you create and scope an API key, you can use it in your application. How you implement it in your code depends if you are using an ArcGIS REST API, ArcGIS client API, or open source API.

All ArcGIS location services support a token parameter. The value of this parameter can be any valid access token, including an API key. Every time you want to access ArcGIS location services and/or private content items, you need to set the token parameter value to an API key for every request.

Examples

ArcGIS REST APIs

This example shows how to access the geocoding service directly by setting the token parameter to an API key. To run it, click the link and replace <YOUR_API_KEY> with an API key that is scoped to access the geocoding service.

https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&singleLine=1600%20Pennsylvania%20Ave%20NW,%20DC&token=<YOUR_API_KEY>

Use dark colors for code blocksCopy
1
GET geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&singleLine=1600 Pennsylvania Ave NW, DC&token=<YOUR_API_KEY> HTTP/1.1

ArcGIS APIs

If you are using an ArcGIS API, the API key value is typically set once when the application is initialized and is applied every time a request is made to a location service.

The examples below show how to use an API key to access the basemap styles service.

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for JavaArcGIS Maps SDK for Qt (C++)ArcGIS Maps SDK for Qt (QML)
Expand
Use dark colors for code blocksCopy
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
44
45
46
47
48
49
50
51
      esriConfig.apiKey= "YOUR_API_KEY";
      const map = new Map({
        basemap: "arcgis-topographic" // Basemap layer
      });

      const view = new MapView({
        map: map,
        center: [-118.805, 34.027],
        zoom: 13, // scale: 72223.819286
        container: "viewDiv",
        constraints: {
          snapToZoom: false
        }
      });

Open source APIs

If you are using an open source or third-party API, you can set the API key using a class or property (if they are available), otherwise, you need to add a token parameter with your API key for each service request.

The examples below show how to use an API key to access the basemap styles service.

Esri LeafletEsri LeafletMapLibre GL JSOpenLayersCesiumJS
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
const apiKey = "YOUR_API_KEY";
const basemapEnum = "ArcGIS:Topographic"
const layer = L.esri.Vector.basemap(basemapEnum, { apiKey: apiKey });
const map = L.map('map', {
  center: [34.027, -118.805]
});
map.setView([34.027, -118.805], 13); // latitude, longitude, zoom level, scale: 72223.819286

API key management

To create and manage API keys, you use the developer dashboard. The dashboard allows you to add, delete, edit, and monitor API key usage. For additional security, you can also set the API key scopes and referrers.

API keys management

API key scopes

A scope is a specific type of ArcGIS functionality that you can grant to an API key. A scope provides access to an ArcGIS location service, a subset of service functionality, or a private content item for data services.

ArcGIS location service scopes

A location service scope grants an API key access to a ready-to-use ArcGIS location service or subset of service functionality. You can set location service scopes if you have an ArcGIS Developer account or ArcGIS Online account.

When you create a new API key, the following scopes are set by default if you have an ArcGIS Developer account:

  • Basemaps
  • Geocoding (not stored)
  • Routing
  • Service areas

If you have an ArcGIS Online account, basemaps and geocoding (not stored) are set by default.

After creating an API key, use your developer dashboard to add or remove the scopes required for your application.

Available location service scopes

The scopes available depend on the type of ArcGIS account you have and if pay-as-you-go is enabled.

ArcGIS Developer accountArcGIS Developer account
(pay-as-you-go enabled)
ArcGIS Online accountArcGIS Enterprise account
Basemaps
Places
Geocoding (not stored)
Geocoding (stored)
Routing
Routing (optimized)
Service area
Multi-vehicle routing
Closest facility
Location allocation
Travel cost matrix
GeoEnrichment
Full supportPartial supportNo support
    ArcGIS Developer

    Example of location service scopes if you have an ArcGIS Developer account (pay-as-you-go not enabled).

    ArcGIS data service scopes

    A data service scope grants an API key access to a private hosted layer (item) and its associated data service. The types of data services an API key can be scoped to are feature services, vector tile services, and map tile services. To learn how to create these services, go to Introduction to data services.

    When an API key is scoped to a data service, it allows an application to access the service operations. For example, you can display data from the service or you can perform other operations such as editing features if you have a feature service.

    A data service scope can also be used to access file and web map items that are related to data services.

    Data service items

    The following is a list of the hosted layer items and data services you can scope to an API key.

    ArcGIS Developer accountArcGIS Online accountArcGIS Enterprise account
    Hosted feature layer item (feature service)
    Hosted vector tile layer item (vector tile service)
    Hosted map tile layer item (map tile service)
    Full supportPartial supportNo support

      Other items

      The following is a list of related items you can scope to an API key.

      ArcGIS Developer accountArcGIS Online accountArcGIS Enterprise account
      GeoJSON file (item)
      CSV file (item)
      Web map (item)
      Full supportPartial supportNo support
        API keys content item scopes

        Example of content items that can be scoped for ArcGIS Developer accounts.

        API key referrers

        An HTTP referer 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.

        You can use your developer dashboard to set referrer headers. When an API key has a specific HTTP referer header set, services can confirm that an incoming request's referrer matches one of the valid referrers assigned to that key.

        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 API key to be used on both https://dev.your-app.com and https://your-app.com. While it is also possible to restrict API key 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.

        Monitor usage

        You can use your developer dashboard to view API key usage for each ArcGIS location service. You can monitor usage over 3, 7, or 30 days, or for the current or last billing cycle.

        API keys monitor usage

        Example of location service usage for an API key.

        Billing

        Applications that use API keys to access ArcGIS location service are billed differently depending on the type of ArcGIS account you have.

        ArcGIS Developer accounts have a free tier of usage for some ArcGIS location service transactions. To access location service functionality that doesn't have a free tier, you need to enable pay-as-you-go needs. For transactions to continue beyond the free tier, pay-as-you-go also needs to be enabled. To learn more about transaction pricing, go to the Pricing page.

        ArcGIS Online accounts consume credits for some ArcGIS location service transactions. To learn more about credit consumption and pricing, go to Understanding credits.

        Limitations

        Account types

        API keys are only available to ArcGIS Developer accounts or ArcGIS Online accounts with a user type of Creator (or higher). API keys are not available with ArcGIS Enterprise. API keys are not available with any other ArcGIS account type such as Public, Education, Personal Use, and others.

        Max keys

        There is a 100 key limit for ArcGIS Developer 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.

        Private hosted layer items and data services

        API keys can be used with ArcGIS Developer accounts to provide limited access to private hosted layer (items) and data services.

        API keys cannot be used with ArcGIS Online accounts to access private hosted layer (items) and data services.

        The maximum number of content items e.g. feature layers, vector tile layers, or map tile layers you can scope to an API key is 100.

        For more information about the type of private hosted layer (items) you can scope and the operations you can perform with data services, go to ArcGIS data service scopes.

        Tutorials

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