Authentication

ArcGIS REST JS includes a comprehensive set of classes for managing authentication. Each helper corresponds with one of the main authentication methods discussed in Security and authentication in the Mapping APIs and location services guide.

These classes are:

These managers handle much of the complexity of dealing with authentication including:

  • Performing OAuth authentication workflows.
  • Automatically refreshing credentials when they expire.
  • Obtaining credentials for a specific instance of ArcGIS Server.
  • Passing credentials between clients and servers.

How authentication managers work

Each authentication manager has several static methods to help construct the manager object. These static methods are the preferred way to create the manager objects and implement specific workflows and patterns.

The general workflow is:

  1. Get an access token or OAuth 2.0 credentials.
  2. Create the manager using the correct helper method for your authentication workflow.
  3. Access services with the authentication option.

API key manager

An instance of ApiKeyManager can be created with the ApiKeyManager.fromKey() method.

Use dark colors for code blocks
   
1
2
3
import { ApiKeyManager } from "@esri/arcgis-rest-request";

const apiKey = ApiKeyManager.fromKey("YOUR_API_KEY");

Example

Use an API key to authenticate a request

If your application needs to access location services, use an API Key from your developer dashboard. When using an API key, make sure that it is properly scoped to the services you are accessing.

Because of their simplicity, API keys can be passed directly to the authentication parameter.

  1. Reference the library.
  2. Get an API key from your dashboard.
  3. Set the API key.
Use dark colors for code blocks
         
1
2
3
4
5
6
7
8
9
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { geocode } from "@esri/arcgis-rest-geocoding";

geocode({
  address: "1600 Pennsylvania Ave",
  postal: 20500,
  countryCode: "USA",
  authentication: ApiKeyManager.fromKey("YOUR_API_KEY")
})

To learn more, go to the tutorials.

ArcGIS identity manager

An instance of ArcGISIdentityManager can be created with several different methods including helper methods for OAuth 2.0 workflows.

Use dark colors for code blocks
        
1
2
3
4
5
6
7
8
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";

ArcGISIdentityManager.beginOAuth2({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "YOUR_REDIRECT_URI"
}).then((manager) => {
  console.log(manager);
});

Example

Use ArcGIS identity with OAuth 2.0

When your app requires access to Esri secure user content or if you are distributing your app through ArcGIS Marketplace, you should implement OAuth 2.0 to obtain an ArcGIS identity.

The ArcGIS REST JS request package includes the ArcGISIdentityManager to authenticate users with their ArcGIS Online or ArcGIS Enterprise accounts. The ArcGISIdentityManager also includes helper methods to simplify the authentication process and manage credentials once they are obtained.

  1. Reference the library.
  2. Go to your dashboard.
  3. Create or use an existing application.
  4. Configure the redirect URL for your application.
  5. Get the client ID and redirect URI for your application.
  6. Set the client ID.
Use dark colors for code blocks
                  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";

// register your own app to create a unique clientId
const clientId = "abc123"

// send the user to the authorization page
ArcGISIdentityManager.beginOAuth2({
  clientId,
  redirectUri: 'https://yourapp.com/authenticate.html'
})
  .then(authenticationManager => {
    geocode({
      address: "1600 Pennsylvania Ave",
      postal: 20500,
      countryCode: "USA",
      authentication: authenticationManager
    })
  })

After the user authorizes your application they will be taken to the page specified by the redirectUri which should complete the oAuth 2 process.

Use dark colors for code blocks
             
1
2
3
4
5
6
7
8
9
10
11
12
13
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";

const clientId = "abc123"

/**
 * after the user authorizes the application they will be redirected to
 * the page defined in redirectUri which will need to complete the
 * authentication process.
 **/
ArcGISIdentityManager.completeOAuth2({
  clientId,
  redirectUri: 'https://yourapp.com/authenticate.html'
});

To learn more, go to the authentication tutorials.

Application credential manager

An instance of ApplicationCredentialsManager can be created with the ApplicationCredentialsManager.fromCredentials method:

Use dark colors for code blocks
        
1
2
3
4
5
6
7
8
import { ApplicationCredentialsManager } from "@esri/arcgis-rest-request";

ApplicationCredentialsManager.fromCredentials({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET"
}).then((manager) => {
  console.log(manager);
});

Example

  1. Reference the library.
  2. Go to your dashboard.
  3. Create or use an existing application.
  4. Get the client ID and client secret for your application.
  5. Create an instance of ApplicationCredentialsManager with the client id and client secret
Use dark colors for code blocks
              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { ApplicationCredentialsManager } from "@esri/arcgis-rest-request";
import { geocode } from "@esri/arcgis-rest-geocoding";

ApplicationCredentialsManager.fromCredentials({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET"
}).then((manager) => {
  geocode({
    address: "1600 Pennsylvania Ave",
    postal: 20500,
    countryCode: "USA",
    authentication: manager
  })
});

Access services with authentication

The authentication option on most methods accepts one of the three manager classes. Use the authentication to make a request to a service.

Use dark colors for code blocks
           
1
2
3
4
5
6
7
8
9
10
11
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { solveRoute } from "@esri/arcgis-request-routing";

solveRoute({
  stops: [
    [-117.195677, 34.056383],
    [-117.918976, 33.812092],
   ],
   authentication: ApiKeyManager.fromKey("YOUR_API_KEY")
})
  .then(response)

If you have an access token from another source, you can pass it directly to the authentication option; however this is not recommended. If you directly pass an ArcGIS Identity or application credential, ArcGIS REST JS will skip most of its error handling (which is a key feature), so this should be used with caution.

Use dark colors for code blocks
          
Change line
1
2
3
4
5
6
7
8
9
10
import { solveRoute } from "@esri/arcgis-request-routing";

solveRoute({
  stops: [
    [-117.195677, 34.056383],
    [-117.918976, 33.812092],
   ],
   authentication: "ACCESS_TOKEN_OR_API_KEY"
})
  .then(response)

Refresh a credential

Both ArcGISIdentityManager and ApplicationCredentialsManager generate short lived credentials by default. Both of these classes have a canRefresh property that indicates if the credentials can be refreshed after they expire. Credentials can be refreshed by calling the refreshCredentials method.

Use dark colors for code blocks
         
1
2
3
4
5
6
7
8
9
// assuming `manager` is an instance of `ArcGISIdentityManager`
// or `ApplicationCredentialsManager`.
if(manager.canRefresh) {
  manager.refreshCredentials().then(()=> {
    console.log("Credentials refreshed");
  }).catch((error) => {
    console.log("Error refreshing credentials");
  })
}

Tokens are also automatically refreshed in the following cases if the canRefresh property is true:

  • If a token is used for a request 5 minutes or less before a token expires, the token will be refreshed and the new token will be used for the request.
  • If a service responds with an invalid token error, the token will be refreshed and the request retried with the new token.

You can also use canRefresh and refreshCredentials() to periodically refresh the credentials while the user is using your application.

Use dark colors for code blocks
          
1
2
3
4
5
6
7
8
9
10
// ideally this would run sometime after your application loads
if (manager.canRefresh) {
  // refresh the credentials to ensure we have a fresh access token which will expire in 30 minutes
  manager.refreshCredentials().then(()=>{
    // once we have a fresh token set a timeout to refresh every 25 minutes.
    setTimeout(()=>{
      manager.refreshCredentials()
    }, 25 * 60000)
  })
}

Handle errors

When using ArcGISIdentityManager and ApplicationCredentialsManager ArcGIS REST JS will throw additional errors related to managing the token and token lifecycle.

These errors provide more insight into the token lifecycle and are discussed more in the error handling topic.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.