Get Token Service

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


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.


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

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


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

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)

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.

The response has been abbreviated in the example where "..." is noted.

See Also

API Analysis/Report Services

API Standard Geography Services

API Utility services