Access tokens

What is an access token?

An access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more is an authorization string that provides access to secure ArcGIS resources such as ArcGIS applications, ArcGIS servicesA service, also known as an ArcGIS service, is software that supports an ArcGIS REST API and provides geospatial functionality or data. A service can be hosted by Esri or in ArcGIS Enterprise.Learn more, ArcGIS Location ServicesArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services.Learn more, and ArcGIS portal servicesA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise.Learn more. You can get an access token by implementing a type of authentication. You use an access token to make HTTP requests to authenticated services. The services the token can access and the operations it can perform are determined by the privileges associated with the token.

Below is an example of 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 access token:

1
AAPT85fOqywZsicJupSmVSCGrjmBjlVZupd64H9kjIjy5FrwIJkpxFMIvd88p32f1vWWpuyzGx7-1nPCMc4XljyuVu-fQSxU4r1Nq17OQo5kjJBVcAw1bKKYM9GYeB98hlK9cwRNzi8H7z3SNb8hCLYvrNwKhXPJo971vH22psnikowztg6ckFD-1zi3TasXKe0e3sSNrmBRunl0SLM7hPgNzuPQkvVES1fDgDL-Thsc2XU.AT2_WilXzfTa

Types of access tokens

There are three types of access tokens that you can create: API keys, user access tokens, and app tokens. The type of access token created depends on the type of authentication you use to create it. The main difference between the tokens is how you create them, the duration they are valid for, the account they are associated with, and who is billed for service usage.

How to use an access token

You can use an access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more to make HTTP requests to ArcGIS services. To do so, you need to set the token parameter of the request to include the access token. If the token is authenticated successfully, the request is granted access to the service operation or resource.

Steps to use an access token:

1. Get an access token by implementing authentication.

2. Find the ArcGIS service URL you want to access.

3. Set the token parameter.

4. Access the ArcGIS service endpoint or operation.

1
https://<ARCGIS_SERVICE_URL>?token=<YOUR_ACCESS_TOKEN>

Access token privileges

Access tokensAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more have privileges associated with them that determine the ArcGIS services, service operations, and content itemsAn item, also known as a content item, is a resource stored in a portal such as a web map, hosted layer, style, script tool, file, or notebook.Learn more they can access. Privileges are assigned to access tokens as part of the authentication process.

The privileges of an access token are based on the privileges of the accountAn ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription.Learn more used to create it. With API keyAPI key authentication is a type of authentication that uses an API key to authenticate requests to ArcGIS services and secure portal items.Learn more and app authenticationApp authentication is a type of authentication that grants a short-lived access token based on an OAuth 2.0 client ID and client secret, authorizing an application to access ArcGIS services and items.Learn more, specific privileges from your account can be assigned to access tokens. With user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more, access tokens inherit all of the privileges of the signed-in user's account.

View access token properties

You can view the properties and capabilities of an access token by making a /self request to the portal serviceA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise.Learn more. This allows you to get information such as 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 the access token.
• Access token expiration date.
• Organization ID of the organizationAn organization a list of members from the same business, association, or entity who can sign in, access tools and applications, and collaborate with other members in a portal. All members have an ArcGIS account and are approved by an administrator to access the same portal.Learn more the access token belongs to.
• Client IDA Client ID is an identifier associated with an application that assists with client / server OAuth 2.0 authentication for ArcGIS client APIs.Learn more of the associated 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.
• Item IDAn item ID is a unique identifier representing a single item stored, managed, and accessed in a portal, such as a web map, hosted layer, or file.Learn more of the associated developer credentials.
• Owner of the associated developer credentials.

The steps to get an access token's properties are:

1. Find the URL to your portal serviceA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise.Learn more.
2. Define the /self request.
3. Set the token and appInfoToken parameters to your access token.

URL request

1
https://<PORTAL_URL>/self?token=<YOUR_ACCESS_TOKEN>&appInfoToken=<YOUR_ACCESS_TOKEN>&f=pjson

Required parameters

API key access token properties

This example shows a sample response from a /self request for an API key access token that has specific 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 assigned to it. This type of access token is obtained from API key authentication.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    "appInfo": {
        "appId": "<CREDENTIAL_CLIENT_ID>",
        "itemId": "<CREDENTIAL_ITEM_ID>",
        "appOwner": "<USERNAME_OF_OWNER>",
        "orgId": "<ORGANIZATION_ID>",
        "appTitle": "<CREDENTIAL_TITLE>",
        "privileges": [
            "premium:user:basemaps",
            "premium:user:elevation",

User access token properties

This example shows a sample response from a /self request for a user access token that impersonates an ArcGIS accountAn ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription.Learn more. This type of access token is known as a user access token and is primarily obtained from user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more. It can also be obtained from certain workflows in API key and app authentication.

The /self response for this type of token returns additional properties pertaining to the impersonated account, including:

• The full name associated with the ArcGIS account
• The email associated with the ArcGIS account
• Timestamp of the last account sign-in
• All privileges the account has
• All groups that the account belongs to

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
{
    "username": "<USERNAME>",
    "udn": null,
    "id": "<USER_ID>",
    "fullName": "<USER_FULL_NAME>",
    "categories": [],
    "emailStatus": "notverified",
    "firstName": "<USER_LASTNAME>",
    "lastName": "<USER_FIRSTNAME>",
    "preferredView": null,

App access token properties

This example shows a sample response from a /self request for an app access token that has specific 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 assigned to it. This type of access token is obtained from app authentication.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    "appInfo": {
        "appId": "<CREDENTIAL_CLIENT_ID>",
        "itemId": "<CREDENTIAL_ITEM_ID>",
        "appOwner": "<USERNAME_OF_OWNER>",
        "orgId": "<ORGANIZATION_ID>",
        "appTitle": "<CREDENTIAL_TITLE>",
        "privileges": [
            "premium:user:basemaps",
            "premium:user:elevation",

Code examples

The following code examples show how to use access tokens to make requests to ArcGIS services.

1
2
curl https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/outdoor? \
-d "token=<YOUR_ACCESS_TOKEN>"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
    "glyphs":"https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf?token=YOUR_API_KEY",
    "layers":[
        {
            "filter":["in","_symbol",0],
            "id":"Land",
            "layout":{},
            "minzoom":0,
            "paint": {
                "fill-color": {

1
2
3
4
curl https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates \
-d "f=pjson" \
-d "address=1600 Pennsylvania Ave NW, DC" \
-d "token=<YOUR_ACCESS_TOKEN>"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
    "spatialReference": {
      "wkid": 4326,
      "latestWkid": 4326
    },
    "candidates": [
      {
        "address": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
        "location": {
          "x": -77.036548499999995,

1
2
3
4
5
curl https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0/query? \
-d "where=1=1" \
-d "outFields=*" \
-d "f=json" \
-d "token=<YOUR_ACCESS_TOKEN>"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
    "objectIdFieldName":"OBJECTID",
    "uniqueIdField":{"name":"OBJECTID","isSystemMaintained":true},
    "globalIdFieldName":"",
    "geometryProperties":{"shapeAreaFieldName":"Shape__Area","shapeLengthFieldName":"Shape__Length","units":"esriMeters"},
    "geometryType":"esriGeometryPolygon",
    "spatialReference":{"wkid":102100,"latestWkid":3857},
    "fields":[
        {
            "name":"OBJECTID",

1
2
3
curl https://www.arcgis.com/sharing/rest/content/items/<ITEM_ID> \
-d 'f=pjson' \
-d 'token=<YOUR_ACCESS_TOKEN>'

1
2
3
4
5
6
7
8
9
10
11
{
    "id": "ITEM_ID",
    "owner": "OWNER",
    "orgId": "ORG_ID",
    "created": "DATE_CREATED",
    "modified": "DATE_MODIFIED",
    "guid": null,
    "name": null,
    "title": "ITEM_TITLE",
    "type": "ITEM_TYPE"

Tutorials