App credential authentication

App credential authentication is a type of authentication that grants a short-lived access token based on a set of application credentials, authorizing an application to to access ready-to-use services on behalf of its developer. The app credentials workflow adheres to the OAuth2.0 authorization protocol, and uses a set of application credentials with a client_credentials grant type to secure client login.

How app credential authentication works

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 from ArcGIS, 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 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 credentials could potentially also access billable ArcGIS location services 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 ArcGIS 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:

   Use dark colors for code blocksCopy

   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 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

Response object

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

Code examples

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.

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":[]
  }
}

Billing information

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

Limitations of app credential authentication

The limitations of app credential authentication are:

• Tokens obtained with application credentials can only read private content and services owned by the user who created the application.
• Applications cannot create, update, share, modify, or delete content (layers, files, services, maps.) In other words, they are read only.
• Applications that use application credentials cannot be listed in the ArcGIS Marketplace.

Read only

If a user has private content associated with their account, content that has not been shared with anyone, applications can only read or query the content. Applications are not allowed to modify content, or to upload, create, modify, or delete content that belongs to a user's account.

To understand why this restriction exists consider the following scenario:

A user creates an application and generates an application credential token with a client_id. They give this token to a client side web application to access a premium service like routing. An attacker sees the token and uses the token to delete all the content in that users account. This kind of action would be possible without this restriction in place.

If you want to access private content or content that has been shared with another user, implement user authentication.

Content restrictions

If you create application credentials and use them in your own applications, they can only access private content that you own.

To understand why this restriction exists consider the following scenario:

User X creates an application A. Application A has read access to everything that user X owns. If user Y shares content (map, layer, etc.) with user X, but user Y doesn't know about application A, if things weren't locked down like this, application A could make use of services provided by user Y without user Y knowing about it. If application A made resources available to the public user Y would essentially be sharing their content publicly when they were shared with user X.

If you want to access private content owned by another account or content that has been shared with another user, implement user authentication authentication pattern.

Marketplace restrictions

Applications that use app credential authentication will not be approved for listing in the ArcGIS Marketplace. Your application must implement user authentication to be considered for listing in the marketplace.

Tutorials