API keys

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.

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.

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

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 (see Limitations).

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.

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

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 content item scopes

A content item scope grants an API key access to a private content item in ArcGIS that you own.

If you have an ArcGIS Developer account, you can set a content item scope. This functionality is only available for a limited set of item types (see table below). You can only perform operations that are read-only and operations such as editing and updating hosted data services are not supported.

If you have an ArcGIS Online account, you cannot use API keys to access private content items. To do so you need to implement OAuth 2.0 using an ArcGIS identity. Using OAuth 2.0, as long as the account has the correct user type and role, all service functionality is supported and editing and updating hosted data services is supported.

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

Available content item scopes

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

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 content items

For ArcGIS Developer accounts, API keys provide limited access to private content items in ArcGIS. ArcGIS Online accounts cannot be used to access private content items in ArcGIS.

For more information about the type of private items you can scope and the operations you can perform, go to ArcGIS content item scopes.

Tutorials