Authentication and access tokens

To build applications that use ArcGIS resources and services, you must first implement authentication to obtain an access token. There are three types of authentication: API key authentication, user authentication, and app authentication. ArcGIS REST JS provides authentication managers for each type of authentication which makes it easier to set up authentication once.

API key authentication

If you have ArcGIS Location Platform or ArcGIS Online, you can use API key authentication to authorize secure service requests without requiring users to sign in. This method requires creating an API key credential and embedding a long-lived access token directly in your application, granting access to specific services and content based on the API key’s configured privileges.

API keys can be configured to access specific ArcGIS services and functionality, including location services (such as basemaps, geocoding, and routing), hosted data services, and spatial analysis services. However, they do not support operations that require ArcGIS user account permissions, such as portal administration or content management. See user authentication for those scenarios.

API key authentication is well-suited for building public-facing applications that do not require user sign-in.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import { ApiKeyManager, request } from "@esri/arcgis-rest-request";

const accessToken = "YOUR_ACCESS_TOKEN";
const authentication = ApiKeyManager.fromKey(accessToken);

const url = "https://www.arcgis.com/sharing/rest/community/users";

request(url, {
  authentication,
  params: {
    q: "john" // The query string to search the users against
  }
}).then((response) => {
  console.log(JSON.stringify(response, null, 2));
});

User authentication

If you have ArcGIS Online or ArcGIS Enterprise you can build applications that authenticate users with their ArcGIS account. This process involves creating an OAuth credential, which is used to generate a unique access token tied to the user's privileges. With this token, applications can access all services and resources available to the signed-in user, including location services, spatial analysis, hosted data, secure items, and portal operations such as administration. Access is determined by the user's role and permissions.

User authentication is well-suited for building private applications for your organization that require users to sign in.

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
// Send the user to the authorization screen
app.get("/authorize", function (req, res) {
  ArcGISIdentityManager.authorize(credentials, res);
});

// After authorizing, the user is redirected to /authenticate
app.get("/authenticate", function (req, res) {
  if (credentials) {
    // The user will be redirected with an authorization code we will need to exchange for tokens
    ArcGISIdentityManager.exchangeAuthorizationCode(credentials, req.query.code)
      .then((session) => {
        res.status(200).send(
          "Session successfully acquired. Check your server console to see session details."
        );

        console.log(session);
      })
      .catch((err) => {
        console.error("Error:", err);
        res.status(500).send(err.message);
      });
  } else {
    res.send("Please visit http://localhost:3000/authorize");
  }
});

app.listen(3000, function () {
  console.log("Visit http://localhost:3000/authorize to test the application!");
});

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
    <script type="module">

    /* Use for user authentication */
    const clientId = "YOUR_CLIENT_ID"; // Your client ID from OAuth credentials
    const redirectUri = ""YOUR_REDIRECT_URI""; // The redirect URL registered in your OAuth credentials
    const authentication = await arcgisRest.ArcGISIdentityManager.beginOAuth2({
      clientId,
      redirectUri,
      portal: "https://www.arcgis.com/sharing/rest" // Your portal URL
    });

    </script>

App authentication

If you have ArcGIS Location Platform, ArcGIS Online, or ArcGIS Enterprise you can build applications that authenticate using your app’s OAuth 2.0 credentials instead of a user sign-in. This workflow generates a short-lived access token based on your app’s client ID and client secret. The resulting token is associated with your ArcGIS account and grants access to secure services and items according to your account’s privileges.

App authentication is well-suited for web servers or standalone console scripts. This is to avoid exposing the confidential client_secret value contained within OAuth credentials.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { ApplicationCredentialsManager } from "@esri/arcgis-rest-request";
import { geocode } from "@esri/arcgis-rest-geocoding";

const appManager = ApplicationCredentialsManager.fromCredentials({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET"
});

appManager.refreshToken().then((manager) => {
  geocode({
    address: "1600 Pennsylvania Ave",
    postal: 20500,
    countryCode: "USA",
    authentication: manager
  })
});

More resources