Tutorial: Create an API key

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

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 private applicationA private application is an application that requires users to sign in with an ArcGIS account. It supports user authentication.Learn more shared to your organization.

Prerequisites

Steps

Sign in to your portal

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

1. In your web browser, go to your ArcGIS Enterprise portal and sign in to your portal with your ArcGIS Enterprise account.

Create an API key credential

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

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

   

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.

1. In the Where will you use these credentials? menu, select Private application with selected privileges and access.

   

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

1. If your token does not require item access, select No item access. Then, click Next.

2. Otherwise, select Grant access to specific items.

3. Select the items you want to grant access to. You can select up to 100 items in this menu.

   

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

1. In the Create developer credentials > Privileges window, browse the available privileges.

   Learn more about privileges

   Learn more about privileges

   Browse the table below to view available privileges, privilege strings, and descriptions for ArcGIS Enterprise:

   Category	Label	Privilege string	Description
   Members	View	portal:user:viewOrgUsers	Allow application to view members of the organization.
   Groups	Create, update, and delete	portal:user:createGroup	Allow application to create, edit, and delete their own groups.
   Groups	Join organizational groups	portal:user:joinGroup	Allow application to join groups within your organization.
   Groups	View groups shared with organization	portal:user:viewOrgGroups	Allow application to view groups shared with the organization.
   Groups	Add members from other organizations	portal:user:addExternalMembersToGroup	Allow application to create groups that allow members from other organizations, as well as invite external members to groups.
   Content	Publish hosted feature layers	portal:publisher:publishFeatures	Allow application to publish hosted feature layers from shapefiles, CSVs, etc.
   Content	Publish hosted tile layers	portal:publisher:publishTiles	Allow application to publish hosted tile layers from tile packages, features, etc.
   Content	Publish hosted scene layers	portal:publisher:publishScenes	Allow application to publish hosted scene layers.
   Content	Published hosted tiled imagery layers	portal:publisher:publishTiledImagery	Allow application to publish hosted tiled imagery layers from a single image or collection of images. Requires an ArcGIS Image for ArcGIS Online user type extension.
   Content	Publish hosted dynamic imagery layers	portal:publisher:publishDynamicImagery	Allow application to publish hosted dynamic imagery layers from a single image or collection of images.
   Content	View location tracks	portal:user:viewTracks	Allow application to view members' location tracks via shared track views when location sharing is enabled.
   Content	Publish livestream video	portal:publisher:publishLivestreamVideo	Allow application to publish livestream videos.
   Content	Publish real-time analytics	portal:publisher:publishRealTimeAnalytics	Allow application to publish real-time analytics to analyze and process real-time data using ArcGIS Velocity.
   Content	Publish server-based layers	portal:publisher:publishServerServices	Allow application to publish server-based layers.
   Content	Publish video	portal:publisher:publishVideo	Allow application to publish videos.
   Content	Register data stores	portal:publisher:registerDataStores	Allow application to register video stores.
   Content	Manage feature layer webhooks	portal:publisher:createFeatureWebhook	Allow application to manage webhooks for feature layers.
   Content	Bulk publish from data stores	portal:publisher:bulkPublishFromDataStores	Allow application to bulk publish data from data stores.
   Content	Publish big data analytics	portal:publisher:publishBigDataAnalytics	Allow application to publish big data analytics and process historical observation data using ArcGIS Velocity.
   Content	Publish feeds	portal:publisher:publishFeeds	Allow application to publish feeds.
   Content	Publish knowledge graphs	portal:publisher:publishKnowledgeGraph	Allow application to publish knowledge graphs.
   Sharing	Make groups visible to organization	portal:user:shareGroupToOrg	Allow application to make groups discoverable by your organization.
   Sharing	Make groups visible to public	portal:user:shareGroupToPublic	Allow application to make groups discoverable by the public.
   Features	Edit	features:user:edit	Allow application to edit features in editable layers that are not public, based on the edit options enabled on the layer.
   Features	Edit with full control	features:user:fullEdit	Allow application to add, delete, and update features in an editable, hosted feature layer, regardless of the editing options enabled on the layer.
   Features	Manage feature layer versions	features:user:manageVersions	Allow application to manage feature layer version control settings.
   Premium content	Create notebooks	premium:publisher:createNotebooks	Allow application to create and edit interactive notebooks.
   Premium content	Schedule notebooks	premium:publisher:scheduleNotebooks	Allow application to schedule future automated runs of a notebook.
   Premium content	Create advanced notebooks	premium:publisher:createAdvancedNotebooks	Allow application to import and use ArcPy modules in ArcGIS Notebooks.
   Premium content	Demographic maps	premium:user:demographics	Allow application to access demographic maps in ArcGIS Living Atlas.
   Premium content	Feature report	premium:user:featurereport	Allow application to create feature reports in ArcGIS Survey123.
   Premium content	Run web tools	portal:user:runWebTool	Allow application to run web tools.

   Category	Label	Privilege string	Description
   Members	Update	portal:admin:updateUsers	Allow application to reset passwords, update member account information, and update member categories within your organization.
   Members	Delete	portal:admin:deleteUsers	Allow application to delete member accounts within your organization.
   Members	Invite	portal:admin:inviteUsers	Allow application to invite members to your organization.
   Members	Disable	portal:admin:disableUsers	Allow application to enable and disable member accounts within your organization.
   Members	Change roles	portal:admin:changeUserRoles	Allow application to change the role a member account is assigned. Note, only members with the Administrator role can assign or unassign the Administrator role to other accounts.
   Members	Manage licenses	portal:admin:manageLicenses	Allow application to assign licenses to members of your organization.
   Groups	View all	portal:admin:viewGroups	Allow application to view all groups within your organization.
   Groups	Update	portal:admin:updateGroups	Allow application to update groups within your organization.
   Groups	Delete	portal:admin:deleteGroups	Allow application to delete groups within your organization.
   Groups	Reassign ownership	portal:admin:reassignGroups	Allow application to reassign groups to other members within your organization.
   Groups	Assign members	portal:admin:assignToGroups	Allow application to assign your members to, update your member's group role, and remove your members from groups within your organization.
   Groups	Link to organization-specific group	portal:admin:manageEnterpriseGroups	Allow application to link group membership to an organization-specific group.
   Groups	Create with leaving disallowed	portal:admin:createLeavingDisallowedGroup	Allow application to create and own groups that do not allow members to leave (administrative groups).
   Content	Publish web tools	portal:publisher:publishServerGPServices	Allow application to publish web tools.
   Content	Geoprocessing webhook	portal:admin:createGPWebhook	Allow application to create geoprocessing webhooks.
   Content	Manage servers	portal:admin:manageServers	Allow application to manage servers.
   Content	Manage webhooks	portal:admin:manageWebhooks	Allow application to manage webhooks.
   Content	Create and manage administrative reports	portal:admin:createReports	Allow application to create and manage administrative reports for your organization
   Organization settings	Security and infrastructure	portal:admin:manageSecurity	Allow application to manage the organization's security and infrastructure settings.
   Organization settings	Organization website	portal:admin:manageWebsite	Allow application to manage the organization's website settings.
   Organization settings	Collaborations	portal:admin:manageCollaborations	Allow application to manage the organization's collaborations.
   Organization settings	Member roles	portal:admin:manageRoles	Allow application to manage the organization's member roles.
   Organization settings	Utility services	portal:admin:manageUtilityServices	Allow application to manage the organization's utility service settings

   

2. Select the privileges required by your application and click Next.

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.

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

   

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

   

3. Click Next.

Save the item

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

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

2. In the Summary window, review the properties, privileges, and item access you have set.

   

3. Click Next.

Copy the API key

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

   

2. Click Next.

3. Copy the API key from the window that appears and paste it into your application.

   

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: