Tutorial: Create an API key | Documentation

Learn how to create and manage an API key with ArcGIS Location Platform using API key credentials.

The first window of the Developer credentials creator with the API key credentials option selected. The account used is an ArcGIS Location Platform account.

The developer credentials creation interface in a portal

An API keyAn API key is a long-lived access token created using API key credentials. They are valid for up to one year and are typically embedded directly into client applications.Learn more is a long-lived access token that authorizes your application to access secure services, content, and functionality in ArcGIS. API keys are generated using API key credentialsAPI key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential.Learn more, a type of item you create and manage in your portalArcGIS portal, also known as a portal, is a website with applications and tools that can be used to create, manage, access, and share geospatial content and data. It supports security and authentication, developer credentials, content and data service management, user and group management, and site administration. A portal can be hosted in Esri's infrastructure or your own infrastructure.Learn more. API key credentials contain settings that allow you to generate API keys and manage properties such as their privilegesPrivileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS.Learn more and expiration date.

This tutorial shows you how to use your portalArcGIS portal, also known as a portal, is a website with applications and tools that can be used to create, manage, access, and share geospatial content and data. It supports security and authentication, developer credentials, content and data service management, user and group management, and site administration. A portal can be hosted in Esri's infrastructure or your own infrastructure.Learn more to create API key credentials to do the following:

Generate long-lived API keys and save them in your application.
Configure privileges to allow your API keys to access ArcGIS services, content, and functionality.
Set the expiration date and referrer URLs of an API key.
Manage API keys using the item pageAn item page is a web page in ArcGIS Online or the developer dashboard used to access and manage the properties for an item and the content it references such as a web map, hosted layer, or file.Learn more of your API key credentials.

This tutorial focuses on creating an API key for a public applicationA public application is an application that allows anonymous access without requiring users to sign in with an ArcGIS account. It supports API key or app authentication.Learn more with access to location services.

Prerequisites

You need an ArcGIS Location Platform accountAn ArcGIS Location Platform account, formerly known as an ArcGIS Developer account, is an identity associated with an ArcGIS Location Platform subscription.Learn more.
You need to know the privilegesPrivileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS.Learn more to assign to your API key. The privileges assigned to a key allow your application to access specific ArcGIS services and resources.

Steps

You use your portal to create and manage items, including API key credentials.

In your web browser, go to https://location.arcgis.com, and sign in with your ArcGIS Location Platform account. In the dashboard, click My portal to go to your portal.

Create an API key credential

In your portalArcGIS portal, also known as a portal, is a website with applications and tools that can be used to create, manage, access, and share geospatial content and data. It supports security and authentication, developer credentials, content and data service management, user and group management, and site administration. A portal can be hosted in Esri's infrastructure or your own infrastructure.Learn more, click Content > My content > New item.
Click Developer credentialsDeveloper credentials are a type of item in a portal that contains parameters for authentication. There are two types of developer credentials: API key credentials and OAuth credentials.Learn more > API key credentialsAPI key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential.Learn more and click Next.

Need troubleshooting help?

If the Developer credentials option is not visible when creating a new item, your ArcGIS Online account does not have the correct permissions. You need an ArcGIS account with a user type of Creator or higher. Learn more about user types in the ArcGIS Online documentation.

If the API key credentials option is not visible when creating developer credentials, your ArcGIS Online account does not have the correct permissions. You need an ArcGIS account with a user type of Creator or higher. Your account must also have these additional privileges:

General privileges > Content > Generate API keys
General privileges > Content > Assign privileges to OAuth 2.0 applications

Your organization administrator can grant you these privileges using a custom role. To learn how, go to the ArcGIS Online documentation.

Select application type

You can configure your API key credentials in this menu to align their capabilities with the type of application you are building. This menu determines the privileges that will be available for selection in the next steps.

In the Where will you use these credentials? menu, select Public application.

Warning
If you are not building a public application, select one of the Private application options in this menu instead. These options allow access to additional privileges under the General and Admin categories, and should not be embedded in public applications.
Click Next.

Select item privileges (optional)

If your application will require access to specific private items, you will need to configure your developer credentials to access them. The Item access menu allows you to browse your portal's content and grant your API key access to specific items.

If your token does not require item access, select No item access. Then, click Next.
Otherwise, select Grant access to specific items.
Select the items you want to grant access to. You can select up to 100 items in this menu.
Click Next.

Select service privileges

You can configure the settings of API key credentials to configure the privilegesPrivileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS.Learn more of generated API keys. For an API key to work in your application, it needs to have the correct privileges to access the content and services your app is using. Select the privileges your app requires in this menu.

In the Create developer credentials > Privileges window, select the privileges required by your application.

Learn more about privileges

Browse the table below to view available privileges, privilege strings, and descriptions for public applicationsA public application is an application that allows anonymous access without requiring users to sign in with an ArcGIS account. It supports API key or app authentication.Learn more created with ArcGIS Location Platform:

Category	Label	Privilege string	Description
Basemaps	Basemap styles service	`premium:user:basemaps`	Allow application to access the basemap styles service. Learn more
Basemaps	Static basemap tiles	`premium:user:staticbasemaptiles`	Allow application to access the static basemap tiles service. Learn more
Static maps	Static maps service (beta)	`premium:user:staticMaps`	Allow application to access the static maps service. Learn more
Places	Place finding	`premium:user:places`	Allow application to access the places service. Learn more
Geocoding	Geocode (stored)	`premium:user:geocode:stored`	Allow application to access the geocoding service and perform stored geocodes. Learn more
Geocoding	Geocode (not stored)	`premium:user:geocode:temporary`	Allow application to access the geocoding service and perform geocodes that are not stored. Learn more
Routing	Routing	`premium:user:networkanalysis:routing`	Allow application to access the routing service and perform standard routing operations. Learn more
Routing	Closest facility	`premium:user:networkanalysis:closestfacility`	Allow application to access the routing service and perform closest facility routing operations. Learn more
Routing	Location allocation	`premium:user:networkanalysis:locationallocation`	Allow application to access the routing service and perform location allocation operations. Learn more
Routing	Optimized routing	`premium:user:networkanalysis:optimizedrouting`	Allow application to access the routing service and perform optimized routing operations. Learn more
Routing	Origin/destination cost matrix	`premium:user:networkanalysis:origindestinationcostmatrix`	Allow application to access the routing service and generate travel cost matrices. Learn more
Routing	Service area	`premium:user:networkanalysis:servicearea`	Allow application to access the routing service and generate service areas. Learn more
Routing	Multi-vehicle routing	`premium:user:networkanalysis:vehiclerouting`	Allow application to access the routing service and perform fleet routing operations. Learn more
Routing	Last mile	`premium:user:networkanalysis:lastmiledelivery`	Allow application to access the routing service and perform routing operations for last mile delivery. Learn more
Routing	Snap to roads	`premium:user:networkanalysis:snaptoroads`	Allow member to perform network analysis tasks such as snap GPS track points to roads. Learn more
Data enrichment	GeoEnrichment service	`premium:user:geoenrichment`	Allow application to access the GeoEnrichment service. Learn more
Elevation	Elevation service	`premium:user:elevation`	Allow application to access the elevation service. Learn more

Privilege selection window (ArcGIS Location Platform)

Click Next.

Need troubleshooting help?

If the Privileges window is not visible when creating API key credentials, your ArcGIS Online account does not have the correct permissions. You need an ArcGIS account with a user type of Creator or higher. Your account must also have these additional privileges:

General privileges > Content > Generate API keys
General privileges > Content > Assign privileges to OAuth 2.0 applications

Your organization administrator can grant you these privileges using a custom role. To learn how, go to the ArcGIS Online documentation.

If you don't see a specific privilege in the Privileges window, there are several possible reasons:

The application type you selected may only allow a limited set of privileges. To access a broader set of privileges, choose a different type of application in the Where will you use these credentials? menu.

Certain location services are only available for ArcGIS Location Platform. Check the privileges available for your product type in Security and authentication > Privileges.
If you have an ArcGIS Location Platform account, you need to enable pay-as-you-goPay-as-you-go is a payment option in ArcGIS Location Platform that allows you to exceed the free usage tier and pay for additional location services and capabilities based on usage.Learn more in the Billing section of your dashboard to access some services, such as the GeoEnrichment service.
If you have an ArcGIS Online account, your account may not have the correct role to access the services you need. Contact your organization administrator.

Set the expiration date and referrers

API key credentials generate long-lived access tokens called API keys. API keys are valid for up to one year, and their expiration date is set when they are generated. You can also set referrers on an API key, which restrict the key to only be usable from authorized domains.

In the Create developer credentials window, click on the Expiration date field. Set the expiration date of the access token to one month from today's date.
Set the Referrers field to the web domains you would like to restrict the access token to. This is highly recommended for security purposes. To learn more about referrers, go to API key credentials.
Click Next.

Save the item

After configuring the properties of your API key credentials, save the credentials as a new item.

In the Create developer credentials window, set the following properties:
- Title: My API key credentials
- Folder: Developer credentials (Create a new folder)
- Tags: Add tags related to the privileges of the credentials.
- Description: Describe the application that these developer credentials will be used in.
Click Next.
In the Summary window, review the properties, privileges, and item access you have set.

Warning
The API key access tokens that this credential generates will grant access to the privileges listed here. If any items were selected, ensure they do not contain any sensitive or confidential data. Follow security best practices regarding API key rotation, expiration date, and referrer URLs.
Click Next.

Copy the API key

In the Create developer credentials > Generate API key window, select Generate the API key and go to item details page. I am ready to copy and save the key.
Click Next.
Copy the API key from the window that appears and paste it into your application.

Attention
This is the only time you will be able to access the value of your API key access token. You will not be able to view it again. To get a new key, you need to regenerate one using the API key credentials item page.

What's next?

Learn how to manage your API key credentials to generate additional keys, edit credential settings, and implement key rotation in the following tutorials:

Manage API key credentials

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

ArcGIS portal

Rotate API keys

Rotate API keys in a deployed application to refresh their expiration dates.

ArcGIS portal REST JS