API keys

An Application programming interface key (API key) is a permanent access token that defines the scope and permission for granting your public-facing application access to specific, ready-to-use services and, with an ArcGIS Developer account, private content hosted in ArcGIS Platform (currently in beta).

Your applications will always require an access token, such as an API key or OAuth 2.0 token, in order to access these resources.

If you already have an ArcGIS account, you can sign in to view your default API key or to create a new API key. An API key is created for you when you sign up for an ArcGIS Developer account.

How API keys work

API key overview

  1. Configure an API key in the developer dashboard.

    An API key is created for you when you sign up for an ArcGIS Developer account.

  2. Set the API key in your client application according to your chosen client API to authenticate with ArcGIS Platform.

Configure your API key

You can create a new API key on the developer dashboard as well as configure an existing API key's name, description, and other settings. Each API key is scoped to a set of ready-to-use services. If you have an ArcGIS Developer account, you can manage the private content and items to which you grant access (currently in beta). API keys can also be restricted to specific referrer header(s).

All API key settings are configured from the developer dashboard, where you also can monitor API key usage.

Using your API key

API endpoints on ArcGIS Platform support a token parameter that will accept either an API key or an OAuth 2.0 token, and to which you can pass your API key. Client APIs support either a single, global API key, which can be used for all requests, or an API key that can be passed to a specific method, or class, or both.

To set an API key in your application, find and copy an API key from your developer dashboard and replace the string YOUR_API_KEY / ACCESS_TOKEN in your code with the API key copied from your dashboard.

ArcGIS JS APIEsri LeafletMapbox GL JSOpenLayersArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)
                                                   
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
<html>

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  <title>ArcGIS Developer Guide: Display a map (2D)</title>
  <style>
    html,
    body,
    #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
  </style>

  <link rel="stylesheet" href="https://js.arcgis.com/4.20//esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.20//"></script>

  <script>
    require([
     "esri/config",
      "esri/Map",
      "esri/views/MapView"
    ],(esriConfig, Map, MapView)=> {
      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
        }
      });
  </script>
</head>

<body>
  <div id="viewDiv"></div>
</body>

</html>

Available services

API keys can be given permissions to access different services. The following ready-to-use services can be accessed with API keys. Some services have multiple "scopes"; for example, you can enable Routing but not Service Area Service on the routing service for an API key. See the set and manage services tutorial to add or remove services from your API key.

ServiceAvailable scopes
Basemap layer serviceBasemaps (enabled by default)
Geocoding serviceGeocoding (stored) / Geocoding (not stored)

Stored / not stored refers to what the developer does with data returned from the service.

Routing serviceRouting / Optimized routing; Closest Facility; Service Area; Location Allocation; Multi-vehicle routing; Origin Destination Cost Matrix
GeoEnrichment serviceGeoEnrichment

Access content and items

Only ArcGIS Developer accounts can use API keys to read private content. If you are a member of an organization with an ArcGIS account, you can use OAuth 2.0 to obtain ArcGIS identity credentials to access private organization and user content and services on your user's behalf.

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. If an API key does not have specific, defined HTTP referers, any request using the API key is valid. When an API key configures a specific HTTP referer header, services can confirm that an incoming request's referrer matches one of the valid referrers affiliated with that key.

You can also 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.

We recommend setting only your domain name (with protocol) as the value for allowed HTTP referer headers.

Monitoring usage

We recommend regularly monitoring your API key usage for irregularities and rotating API keys frequently to prevent unauthorized access. API key usage can be viewed on your developer dashboard.

Billing information

ArcGIS Developer accounts have a free tier for many transactions. See the Pricing page for the billing details for ArcGIS Developer accounts. Transactions beyond the free tier require enabling pay-as-you-go, usage is billed monthly.

ArcGIS Online organizations consume credits for some transactions. See the ArcGIS Online pricing page for information about credits.

Tutorials

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