Application credentials

Application credentials grant a short-lived access token that gives your application permission to access ready-to-use services, such as basemap layers, search, and routing, in ArcGIS Platform. Application credentials use OAuth 2.0 client_id and client_secret parameters and the client_credentials grant type to secure client login.

How application credentials work

Application credentials overview

  1. Create your OAuth 2.0 application in your developer dashboard to receive application credentials (client ID and client secret.)

  2. Create a server-side component to use your application credentials by providing your client ID and client secret to the token endpoint.

  3. Your server-side component uses the application credentials to get an access token with ArcGIS Platform, giving you a temporary token you can share with your client app.

  4. The user of your client application requests a location service that requires authentication.

  5. The client app uses the temporary token supplied by your server to authenticate with ArcGIS Platform and gain access to the requested location service. When that token expires, your client app must request a new token from your server component.

Create a server-side component

Any unauthorized party that accesses your application's credentials could potentially also access billable services on ArcGIS Platform that are metered to your account. When credentials are stored on a client-side application they may be exposed to hackers. To prevent this, your application should implement a server-side component to keep your application credentials secure.

The server side application component also needs to be secured so that only the application and its intended users can access it.

A server-side component calls the OAuth 2.0 token endpoint with your client_id and client_secret using the client_credentials OAuth 2.0 grant_type. The response contains the application credentials in the access_token property. The server-side component then uses these application credentials to make requests to the ArcGIS Platform or passes the token to the client.

  1. Make an OAuth 2.0 REST API POST request to the portal's token endpoint using the request parameters:

        
    1
    2
    3
    4
      https://www.arcgis.com/sharing/rest/oauth2/token
        client_id=YOUR_CLIENT_ID&
        client_secret=YOUR_CLIENT_SECRET&
        grant_type=client_credentials
  2. If successful, the JSON response object contains an access_token property that grants your application permission to work with shared resources. The access_token can be used to make requests to ArcGIS Platform location services. The response also includes an expires_in property indicating when the token will expire. After this time the token will require refreshing in order to continue to access authenticated services.

Get an access token

  1. POST to the token endpoint using the correct parameters, including client ID and client secret.
  2. The JSON response will contain an access_token.
  3. All subsequent ArcGIS REST API requests must include this access_token as authorization whenever a token parameter is required.
  4. Repeat the request when the access_token expires.

Token endpoint

https://www.arcgis.com/sharing/rest/oauth2/token/

A token can only be generated using the POST method over HTTPS. See more details about this endpoint in the REST API documentation.

Request parameters

ParameterRequiredFormatDescription
client_idstringThe registered app's client_id.
client_secretstringThe registered app's client_secret.
grant_typeclient_credentialsYou must include this OAuth 2.0 grant type.
expirationnumberNumber of minutes until token expires: default = 120 minutes; maximum = 20160 minutes (2 weeks).

Response object

    
1
2
3
4
{
    "access_token": "J-S0KLOl5_8U***lMyB9g..",
    "expires_in": 86400
}

Examples

PythonArcGIS-REST-JSNode.jsPHPRubyGocURL
              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import requests  # pip install requests
def get_token():
    params = {
        'client_id': "YOUR_CLIENT_ID",
        'client_secret': "YOUR_CLIENT_SECRET",
        'grant_type': "client_credentials"
    }
    request = requests.get('https://www.arcgis.com/sharing/rest/oauth2/token',
                          params=params)
    response = request.json()
    token = response["access_token"]
    return token
token = get_token()
print(token)

Using the token

Now that you have received the OAuth 2.0 token, it must be included in every request via the token parameter to authorize the request.

The following are examples of an OAuth 2.0 token authorizing GeoEnrichment service demographic data queries.

PythonArcGIS-REST-JSNode.jsPHPRubycURL
         
1
2
3
4
5
6
7
8
9
import requests  # pip install requests
params = {
    'f': 'json',
    'token': 'YOUR_TOKEN_HERE',
    'studyAreas': '[{"geometry":{"x":-117.1956,"y":34.0572}}]'
}
url = 'https://geoenrich.arcgis.com/arcgis/rest/services/World/GeoenrichmentServer/Geoenrichment/enrich'
data = requests.post(url, params=params)
print(data.json())

Token errors

A successful HTTP response will return a status code of 200 with the JSON response format above. If a request fails, you will still receive a status code of 200 but with a failure message. The error description will provide details, but the most common error is due to an expired or invalid token. To resolve these issues, generate a new token and resubmit the request.

         
1
2
3
4
5
6
7
8
9
{
  "error":{
    "code":400,
    "error":"invalid_request",
    "error_description":"code expired",
    "message":"code expired",
    "details":[]
  }
}
HTTP Status Codes
Error codeDescription
400The request sent to the server is not correct. Invalid client ID or client secret.
401Authorization to the requested resource is required.
403Authorization to the requested resource is required.
404The requested resource was not found.
413The request is larger than limits defined by the server. If you're trying to upload an attachment, this error might indicate that the attachment's size exceeds the maximum size allowed.
498The access token provided is invalid or expired.
499A token was required to access the resource.
500The service was not able to fulfill the request, possibly due to invalid input, or the service may not be functioning properly.
501The requested service is not implemented.

Billing information

When you use application credentials, your application's use of location services are metered to your account. ArcGIS Developer accounts are metered to ArcGIS Platform location services. See pricing. ArcGIS Online accounts consume credits for premium content. See premium payment / billing credits information.

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