API key credentials

API key credentials are an item used to create and manage API keys. You create new items by using the Developer credentials tool in your portal. 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.

Create API key credentials

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 include ArcGIS location services such as the basemap styles service and routing service. The available location services depend on the account type, subscription type, and roles of the owner's ArcGIS account.

Edit privileges

You can edit the privileges of your API key credentials to adjust the authorization level of your API keys. Performing this action will invalidate all API keys associated with the credentials. You must regenerate an API key after editing privileges to use it in your application.

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.

Edit item access

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://*.your-app.com will allow the access token to be used on both https://dev.your-app.com and https://your-app.com. While it is also possible to restrict access token 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.

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.

1. Go to Settings on the item page of your API key credentials.

2. Under Application > API keys, click Generate a secondary API key.

   

3. Set an Expiration date for the key and click Generate API key.

4. 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.

1. Go to Settings on the item page of your API key credentials.

2. Under Application > API keys, find the API key you want to regenerate. Click Regenerate API key.

   

3. Click Confirm expiration date and set a new expiration date if desired.

4. 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.

1. Go to Settings on the item page of your API key credentials.

2. Under Application > API keys, find the API key you want to regenerate. Click Invalidate API key.

   

3. 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:

1. Sign in to your portal to view your API key credentials.

2. 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.

3. 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.

   

4. Set the Expiration date of your API key 2 and click Generate API key.

5. Copy the API key 2 and paste it into your application.

6. 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.

The steps to monitor usage vary based on the type of ArcGIS account the credentials were created with: