Overview

You will learn: how to get an access token with OAuth 2.0 to access ArcGIS premium content and services.

Authentication to the ArcGIS REST API is handled by providing a token parameter. There are two ways to obtain tokens: authenticate ArcGIS Online users via OAuth 2.0 or register your application with ArcGIS Online and make a request for a token with your application's credentials. Tokens obtained with application credentials are limited to accessing premium content and services in ArcGIS Online but are easier to generate. Refer to this comparison of user and application authentication for more in-depth information.

Before you begin

Install Postman on your computer so you can create, inspect, and debug HTTP requests.

Steps

Register a new application

In this section you will learn how to create an application and a token with your ArcGIS subscription.

  1. Go to ArcGIS for Developers and sign in.

  2. Click Dashboard + > New Application with the following properties:

    • Title: ArcGIS DevLabs - REST
    • Tags: ArcGIS DevLabs
  3. Click Register your Application.

  4. On the right side, make note of the following values created for your application:

    • Client ID
    • Client Secret
    • Temporary Token

If you want, you can use the temporary token created above for development and testing purposes. Though this token has a short duration and will expire about 2 hours after being created, you can use Generate New Token to create as many tokens as you require.

Generate an access token

In this section you will create a token using OAuth 2.0. These tokens are suited for use in production applications.

  1. Open Postman and click [+] in the tab bar to create a new request.

  2. In the new tab, set the following:

    • Change the HTTP method from GET to POST.
    • Set the URL to https://www.arcgis.com/sharing/rest/oauth2/token.
  3. Click on Body and add the following parameters as Key/Value pairs:

    • client_id: Your application's client id from step 4.
    • client_secret: Your application's client secret from step 4.
    • grant_type: client_credentials
  4. Click Send to run the request.

Explore the response

  1. In the response window, change the view to JSON and it should look something like this:

    {
     "access_token": "I2-6kc3RMq2vcTROGZdFfnT_bKjGfeg2mn1o7F0X-3HLm8qxSWj-apPBpeqB67xJPtu...",
     "expires_in": 7200
    }
    
  2. In Postman click Code below the Send button. Select a programming language and use Postman to generate sample code for your application to run this request.

      var request = require("request");
    
      var options = { method: 'POST',
        url: 'https://www.arcgis.com/sharing/rest/oauth2/token',
        headers:
        { 'content-type': 'application/x-www-form-urlencoded' },
        form:
        { client_id: 'CLIENT_ID_FROM_YOUR_APPLICATION',
          client_secret: 'CLIENT_SECRET_FROM_YOUR_APPLICATION',
          grant_type: 'client_credentials' } };
    
      request(options, function (error, response, body) {
        if (error) throw new Error(error);
    
        console.log(body);
      });
    
      var settings = {
        "async": true,
        "crossDomain": true,
        "url": "https://www.arcgis.com/sharing/rest/oauth2/token",
        "method": "POST",
        "headers": {
          "content-type": "application/x-www-form-urlencoded",
          "accept": "application/json"
        },
        "data": {
          "client_id": "CLIENT_ID_FROM_YOUR_APPLICATION",
          "client_secret": "CLIENT_SECRET_FROM_YOUR_APPLICATION",
          "grant_type": "client_credentials"
        }
      }
    
      $.ajax(settings).done(function (response) {
        console.log(response);
      });
    
    import requests
    
    url = "https://www.arcgis.com/sharing/rest/oauth2/token"
    
    payload = "client_id=CLIENT_ID_FROM_YOUR_APPLICATION&client_secret=CLIENT_SECRET_FROM_YOUR_APPLICATION&grant_type=client_credentials"
    headers = {
        'content-type': "application/x-www-form-urlencoded",
        'accept': "application/json",
        'cache-control': "no-cache",
        'postman-token': "11df29d1-17d3-c58c-565f-2ca4092ddf5f"
        }
    
    response = requests.request("POST", url, data=payload, headers=headers)
    
    print(response.text)
    

Congratulations, you're done!

You have successfully created an access token that you will use to authenticate requests in the other ArcGIS REST API labs.

Challenge

Request a token with a longer duration

By default tokens requested last 120 minutes (2 hours). However, you can pass an additional expiration parameter to request a token valid up to 20160 minutes (2 weeks). Try adding the expiration parameter to your request body and notice how the expires_in value in the response changes.

Get OAuth 2.0 tokens for users

You used your application to generate a token, but you can also authenticate ArcGIS Online users to obtain tokens. Tokens you obtain by authenticating users can also be used to read and modify content in the user's ArcGIS Online account, allowing you to build applications that act on the user's behalf. Credits you consume while using a user's token are billed to that user's organization rather then your own.