API key authentication is a type of authentication that uses long-lived access tokens embedded directly into an application to authenticate requests to location services and private items. The access tokens are called API keys and managed through API key credentials. It is the easiest type of authentication to set up, and is the recommended type of authentication for applications that only access location services.
You can use API key authentication to:
- Create public applications that do not require users to sign in.
- Build applications that only need to access location services or private items such as hosted layers and data services.
- Quickly and easily get access tokens.
- Embed an access token directly into apps that remains valid for up to 1 year.
- Access secure resources with the privileges of your ArcGIS account.
How API key authentication works
API key authentication requires an API key, a type of access token created through API key credentials. API key credentials are an item created in your portal that are used to create API keys and manage their privileges.
The general steps to implement API key authentication are:
-
Create API key credentials to get an API key.
-
Paste the API key access token into your application.
-
Your application uses the API key as an access token to access secure resources.
Your API key must have the correct privileges to access secure resources. It is also recommended that you set referrer URLs in order to enhance the security of the token. These properties are managed through setting page of API key credentials.
API key credentials
API key credentials are an item in your portal used to create and manage API keys. You can manage the settings of API key credentials on their item page to generate up to two API keys, define their privileges and set their expiration dates. API key credentials can also be used to regenerate or invalidate existing API keys.
API key authentication requires API key credentials. The most common pattern is to create a new API key credentials item for each application. API key credentials are used to configure the privileges of an API key, which grant access to specific services, items, and operations in ArcGIS.
Hybrid authentication
In ArcGIS APIs, the Authentication and Identity classes automatically implement a hybrid approach when using both API key authentication and user authentication.
Applications can use both API keys and user authentication, utilizing their API key for location services while the user is signed out and then switching to an access token from user authentication when the user signs in.
Limitations
Service support
The following table provides an overview of the functionality available with each type of authentication:
| API key authentication | User authentication | App authentication | |
|---|---|---|---|
| Location services | |||
| Data services (Item access) | |||
| Spatial analysis services | |||
| Portal service (General privileges) | |||
| Portal service (Admin privileges) |
Account types
API key authentication is only available for ArcGIS Location Platform accounts and ArcGIS Online accounts. API key authentication is not available with ArcGIS Enterprise, or with any other ArcGIS account type such as Public, Education, Personal Use, and others.
To create API key credentials with an ArcGIS Online account, your account must have a role with the Generate API keys privilege. To learn more, go to the FAQ.
API key credentials
Creating credentials: There is no limit to the number of API key credentials and API keys you can create.
Accessing items: An API key credential can be configured to access a maximum of 100 items you own.
Viewing API keys: The value of an API key can only be viewed when the API key is first generated. After a key has been created, its full value is no longer accessible and is not stored in ArcGIS. If you lose the value of an API key, you have to invalidate it and generate a new key using the API key credentials item page.
Changing properties: Editing any of the privileges, item access privileges, or the expiration date of API key credentials will invalidate all associated API keys. New keys can be generated in the Settings section of the API key credentials item page.
API keys (legacy)
Prior to June 2024, API key authentication used API keys (legacy). These API keys still function, but are deprecated and can no longer be created or modified. All new API keys must be created using API key credentials.
API key comparison
The following table shows the differences between legacy API keys and API key credentials:
| API key (legacy) | API key credentials | |
|---|---|---|
| Max number of keys (ArcGIS Location Platform account) | 100 keys | No limit |
| Max number of keys (ArcGIS Online, cumulative across all organization members) | 100 keys | No limit |
| Privileges available | ArcGIS Location Services | ArcGIS Location Services |
| Item access privileges | Supported only for ArcGIS Location Platform | Supported for both ArcGIS Online and Location Platform |
| Max number of items with item access privileges | 100 items per key | 100 items per credential |
| API key expiration date | Not configurable (Does not expire) | Configurable (Lasts up to one year) |
| API key rotation | Not supported | Supported |
Tutorials
Create an API key
Manage API key credentials
Manage previously created API key credentials to regenerate, edit privileges, and edit item access of API keys.
Migrate API keys (legacy) to API key credentials
Migrate from an API key (legacy) created before June 2024 to an API key from API key credentials.