Accessing the service

You can access secured GeoEnrichment services by providing authentication credentials in one of two ways—by prompting end-users to enter their authenticated login or by storing credentials with your application.

Note:

In order to access the GeoEnrichment service, you need an ArcGIS Online subscription to either an Organization plan or a Developer plan. Contact customer service or your account manager for more details.

Once you have a subscription, you can create named users that can access your subscription. Each successful request to the services incurs service credits which are debited from your subscription based on the service used and the results returned from the service. The ArcGIS Online service credits page provides details about service credits for different network analysis services.

An ArcGIS Online subscription is not the same as a current BAO API account, so you will need to create a new AGOL account before accessing the services. You can obtain a 30-day free trial to access the services on the ArcGIS Online home page.

Providing authentication credentials to ArcGIS Online

As a developer, you can provide authentication credentials in one of two ways: by prompting end users to enter their authenticated login or by storing credentials within the application.

Prompting end users to sign in

You can use the Identity Manager component in the client APIs to manage the login process. The Identity Manager simplifies the process of working with secure resources. It handles the process of prompting the user for their credentials, generating a token, and appending it to the request.

For example, If you are using the ArcGIS API for JavaScript to build your application, you can include the IdentityManager dijit in your application to handle authentication. The IdentityManager dijit allows users to sign into ArcGIS Online. Once the user has signed in, any subsequent REST requests made from within that client session using the esri.request object will automatically be part of that authenticated session. Using the IdentityManager also enables single sign on and identity flow for the case of fully hosted JavaScript web applications that are hosted within ArcGIS.com.

Similar facilities are available in the other client APIs.

Storing credentials within the application

You can hardcode the credentials in your application and use the REST API to obtain an access token in exchange for the application credentials. It is your responsibility to keep these application credentials secure. In most cases this implies keeping the credentials on the server and implementing a proxy service. For example, the ArcGIS API for JavaScript provides an example of how to implement such a proxy page.

Authentication using the REST API

The generateToken request in the ArcGIS.com portal allows an application to authenticate using credentials for a named user. Upon successful authentication, the generateToken request returns an access token that you must include in all future service requests.

Tip:

As a best practice, you should use the appropriate client API object model to connect to and authenticate with ArcGIS Online rather than do this directly via the REST API. Performing connection and authentication via the client APIs will free you from authentication details as well as the responsibility of safely handling user credentials during the authentication process.

Request URL

https://www.arcgis.com/sharing/generateToken?parameters

Note:

The generateToken call must be made over https and must be a POST.

Request Parameters

The generateToken request takes the following parameters:

  • username - Username of the user who wishes to get a token.
  • password - Password of user who wishes to get a token.
  • referer - The base URL of the web application that will invoke the services.
    Caution:

    The value for the referer parameter must also be passed in the request header as the referer property. Otherwise, the token will be rejected by the service even if it is generated with valid credentials.

  • expiration - The token expiration time in minutes. The default value for this parameter is 60 minutes. A request with an expired token will be rejected by the service.
    Caution:

    Even though you can request a token with longer expiration time, it is recommended not to do so as the token can be misused by a malicious user. Instead you should frequently request a fresh token that is valid only for a short duration.

  • f - The response format. The value for this parameter must be json.

JSON Response

The response returned by the generateToken request returns the following properties:

  • token - The generated token.
  • expires - The expiration time of the token in milliseconds since Jan 1st, 1970.
  • ssl - If the value is true, all subsequent requests that use the token must be made over https. If the value is false, you are free to make requests that use the token over http or https.

Example

The example shows how to make a generateToken request to get a token that is valid for 15 minutes.

Request URL

https://www.arcgis.com/sharing/generateToken?username=yourUserName&password=yourPassword&referer=http://myserver/mywebapp&expiration=15&f=json

JSON Response

Note that the value for the ssl property is false as the user belongs to an ArcGIS Online organization that has not enforced the policy to make all requests over http.

{
    "token": "Zc07Ivtpoo-AWjVj4u-Is5NiwNQRXHs_2uI17IkTkLxFk5FcBnBr5jiYwko2cyMU",
    "expires": 1354427210436,
    "ssl": false
}

If the request is unsuccessful, the response contains the messages describing the error.

{
    "error": {
        "code": 400,
        "message": "Unable to generate token.",
        "details": [
            "Invalid username or password."
        ]
    }
}