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.

How to use API keys in apps

After you create and configure 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

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

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

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 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 (this scope cannot be removed)
• 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 Online account

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.

If you have an ArcGIS Developer account, you can set the hosted layer and data service scope for items you own. This functionality is only available for hosted layer and file item types related to feature services, vector tile services, and map tile services (see table below). API keys only allow you to perform service operations that are read-only. For example, feature service operations such as editing and updating are not supported. If you need to perform these operations, you need to implement user authentication using OAuth2.0.

If you have an ArcGIS Online account, you cannot use API keys to access private hosted layer (items) and data services. You need to implement user authentication using OAuth2.0.

Available data service scopes

The scopes available depend on the type of ArcGIS account you have.

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.

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.

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