Learn about API key credentials with ArcGIS Enterprise.
API key credentials are an item used to create and manage API keys. You can manage the settings of API key credentials to generate up to two API keys and define their privileges and expiration date. API key credentials can also be used to regenerate or invalidate existing API keys.
Creating API key credentials
Prerequisites
API key credentials can be created using an ArcGIS Enterprise account. The account must have a user type of Creator or higher, as well as a custom role with these privileges:
- General privileges > Content > Assign privileges to OAuth 2.0 applications
- General privileges > Content > Generate API keys
In addition to the account requirements, your ArcGIS Enterprise portal must be version 11.4 or greater. To learn more, go to the Product and account requirements.
Steps
The steps to create API key credentials are described in the Create an API key tutorial:
Create an API key
Create and configure API key credentials to get a long-lived API key access token.
Privileges
API key credentials include a privilege selector that can authorize access to secure ArcGIS services. Once privileges are configured using the selector, the resulting access token will be authorized to access the specified services and perform operations.
The privileges available to API key credentials with an ArcGIS Enterprise account generally include:
- General portal operations, such as creating and managing items and groups.
- Administrative portal operations, such as inviting members, generating reports, and managing organization settings.
- Spatial analysis services for performing feature and raster analysis operations.
The exact privileges available depend on the user type and role of the ArcGIS Enterprise account that created the credentials.
Edit privileges
You can edit the privileges of your API key credentials to adjust the authorization level of your API keys.
-
Go to Settings on the item page of your API key credentials.
-
Under Application > Credentials, click the Edit button. In the warning that appears, click Continue. If this option is not available to your account, please refer to the Product and account requirements for API key authentication.
-
Select a type of application that your key will be used in.
-
Select No item access if you do not want to grant access to any items, or select Grant access to specific items if you want to grant access to certain items in your portal. Then, click Next.
-
Select new privileges for your API key credentials using the privileges window. To view a list of all available privileges, go to Privileges.
-
Click Save to close the window. Then, click the Save button again under Application to update your developer credential.
Item access privileges
API key credentials also include an item access menu used to allow access to specific items in a portal. The resulting access tokens will be authorized to access any items you specify in this menu.
The items available in this menu include all of the items owned by your account with a sharing level of Private, Group, or Organization. API key credentials can be configured to access a maximum of 100 items.
Edit item access
You can edit the items that your API key credentials are authorized to access.
-
Go to Settings on the item page of your API key credentials.
-
Under Application > Credentials, click the Edit button. In the warning that appears, click Continue. If this option is not available to your account, please refer to the Product and account requirements for API key authentication.
-
In the Item access window, select Grant access to specific items to grant access to specific items in your portal.
-
Select items to grant your API key credentials access to.
-
Click Save to close the window. Then, click the Save button again under Application to update your developer credential.
Referrers
A referrer 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. When API key credentials have a specific HTTP referer header set, services can confirm that an incoming request's referrer matches one of the valid referrers assigned to that access token.
Specific domains can be provided or you can use wildcard characters (*) in the subdomain of your allowed referrer. For example https will allow the access token to be used on both https and https. While it is also possible to restrict access token use to specific paths (https), we do not recommend this method because browsers may remove the path due to privacy concerns.
Manage API keys
API key credentials are used to manage API keys, a type of long-lived access token. You can manage the settings of your API keys from the item page of your API key credentials.
The following management actions are supported for API keys:
Generate a secondary API key
You can generate a secondary API key in the same credentials with identical privileges and a new expiration date. The first API key will remain valid. This action is commonly used when Rotating API keys in your application.
-
Go to Settings on the item page of your API key credentials.
-
Under Application > API keys, click Generate a secondary API key.
-
Set an Expiration date for the key and click Generate API key.
-
Copy the API key from the window that appears and paste it into your application.
Regenerate an API key
If you lose access to an API key, you can regenerate it with a new expiration date. This will invalidate the previous key.
-
Go to Settings on the item page of your API key credentials.
-
Under Application > API keys, find the API key you want to regenerate. Click Regenerate API key.
-
Click Confirm expiration date and set a new expiration date if desired.
-
Click Yes, regenerate API key. Copy the API key from the window that appears and paste it into your application.
Invalidate an API key
You can invalidate an API key so that it no longer functions in applications. If your API key gets stolen, it should be invalidated to avoid fraudulent charges to your subscription.
-
Go to Settings on the item page of your API key credentials.
-
Under Application > API keys, find the API key you want to regenerate. Click Invalidate API key.
-
Click Yes, invalidate API key.
Rotate API keys
Up to two API keys can be created in each set of API key credentials. The two API keys have individual expiration dates, but share the same privileges and item access defined by the credentials.
Creating two API keys in one set of credentials allows you to seamlessly rotate keys in your deployed application. When an API key is about to expire, you can generate a second API key and replace it in your application without the app going offline. The high-level workflow for rotating API keys is as follows:
-
Sign in to your portal to view your API key credentials.
-
Check the expiration date of your API key 1. API keys should be rotated in your applications when they are close to their expiration date.
-
When your API key 1's expiration date is approaching, go to Settings > Application in your API key credentials and click Generate a secondary API key.
-
Set the Expiration date of your API key 2 and click Generate API key.
-
Copy the API key 2 and paste it into your application.
-
Deploy your application using the new API key 2 before your API key 1 expires.
Usage tracking
All services and content accessed with API key credentials are tracked. You can monitor the usage of credentials in order to view the consumption of services and the billing amount.
ArcGIS Enterprise developers use their portal to monitor service usage. In ArcGIS Enterprise, individual usage monitoring for API key credentials are not available. To monitor the total service usage within your organization, you can generate a usage report.