Get Token Service

URL	`https://baoapi.esri.com/rest/authentication`

Securely request a short-lived token with valid API credentials in order to use the API Services and Web SDKs.

Output

After securely validating user credentials, the Get Token - Authentication endpoint will return a string-based response containing a short-lived token. This token, while valid, may be used to make Web services requests with the REST and SOAP services and Flex and Silverlight Web SDKs.

Description

The API services and Web SDKs use a token-based authentication scheme to validate user access to the Business Analyst-based services and methods. Access to the various report templates and summarization variables can also vary based on the subscription type.

Initially, a user or application will submit a secure and encrypted request with a valid username and password to the Get Token - Authentication service. After the account credentials are validated, a short-lived token string will be returned to the calling user or application in the response. While valid, this token string will enable a user or application to submit SOAP and REST Web services requests and execute analysis services with the Web SDK components to the API.

Secure Sockets Layer (SSL) is a cryptographic protocol that manages the security and integrity of data traveling across the Internet. SSL is most commonly used between Web browsers and Web servers to create a secure communications link (e.g. Website URLs beginning with https://). SSL can also be used between client applications and Web services such as the Get Token - Authentication service. Many e-commerce Websites, such as banks and online stores, use SSL to encrypt a customer's payment and account information prior to its transfer across the Internet. This will minimize the chance that the sensitive data is intercepted and exploited by any individuals or applications.

The REST and SOAP APIs leverage SSL to securely and efficiently authenticate users and applications, and to issue a short-lived token. Subsequently, this token can be used to make SOAP and REST API Web services requests with the API Web SDKs until it times out. Currently, the tokens are set to timeout after 6 hours however; this is subject to change based on user feedback and ongoing performance evaluations.

Usage Tips

While the token is valid, Web services requests may be submitted to the REST and SOAP APIs and through the API Web SDK components . After timeout, Web services requests will not be handled. The user or client application will have to obtain a new token in order to submit additionally requests. Client applications and systems will need to be designed with token management in mind.
In most cases, it will not be appropriate to embed a API username and password into client-side JavaScript as this may pose a security risk. Instead, a valid token string should be obtained from the Get Token - Authentication service and included in the client-side code/page. One way to do this is to utilize a proxy application that will handle token-based authentication securely on the server side.
While it is possible to obtain a token string through an HTTP GET request (which includes submission of the token request through a browser URL field), we highly recommend that you obtain the token through an HTTP POST request in order to overcome variations in support among browsers and other client applications. This will ensure that your front-end and back-end applications, which leverage the APIs, are fully supported by the majority of systems.
There are security issues with respect to the caching behavior of URL strings in certain client applications such as browsers. Because of this, making HTTP POST requests to the Get Token - Authentication service offers an additional layer of security since parameters are not saved to a URL field. Additionally, you should design your end-user client applications so that they do not make direct token requests to the the Get Token - Authentication service with your API credentials. In general, please be aware of these issues and take the necessary precautions to protect your credentials and investment. For an expanded discussion of security issues, please see The HTTP Protocol and Security Considerations.
Sample code for HTTP POST Requests in Flex, Silverlight, and JavaScript will be provided in the Code Galleries

You can provide arguments to Get Token - Authentication service as defined in the parameters table below.

Parameters

Parameter	Details
password (Required)	Description: A valid REST services password. Syntax: `password=<string>` Notes: The Authentication endpoint supports SSL and encrypts all parameters before submitting the information over HTTPS.
request (Required)	Description: A constant specifying the Get Token request. Syntax: `request=getToken` Notes: The value associated with the `request` parameter will not vary.
username (Required)	Description: A valid REST services user name Syntax: `username=<string>` Notes: The Authentication endpoint supports SSL and encrypts all parameters before submitting the information over HTTPS.
Callback	Description: Wrap the JSON or PJSON response in a named function that can be executed by client-side JavaScript upon receipt. Default: `null` Syntax: `Callback=<string>` Example: `Callback=MyCallbackFunction` Notes: The response will be wrapped in a callback function only if a non-null Callback parameter value is specified and if the response format (the `f` parameter) is set to JSON or PJSON. Callback functions are useful for consuming the service in JavaScript-based client applications as shown in this basic example.
f	Description: The response format. Default: HTML Syntax: `f=<HTML \| XML \| JSON \| PJSON>` Example: `f=PJSON`

Example Usage

Example 1: Generate a timed token for use with API services and Web SDKs. (This is an HTTP GET request. This is for example purposes only. We suggest that you employ an HTTP POST request in order to obtain a token. Please see the Usage Tips given above.)

Request Example (1)

https://baoapi.esri.com/rest/authentication?
request=getToken&
username=<username>&
password=<password>&
f=PJSON

Notes: Substitute valid values for <username> and <password> prior to submitting.

Example Response

JSON Response Syntax

{
  "results": {
    "token": <string>
  }
}

JSON Response Example (1)

{
  "results": {
    "token": "ABC123..."
  }
}

Notes: When using a valid and unexpired token string in the REST or SOAP APIs, associate the token string value with the Token parameter of the REST endpoint, the SOAP method, or when using the SOAP BAOReportHelper class.