The REST and SOAP services and APIs for Flex and Silverlight utilize token-based security to authenticate, validate, and secure Web services transactions. A basic understanding of token-based security is necessary to leverage the API and build client applications which request and consume its services.
The API SOAP and REST services and APIs for Flex and Silverlight use a token-based authentication scheme to validate user access to API service endpoints and API methods. User access can also be associated with other information such as the types of Summary Reports which may be generated or the types of business, demographic, and consumer expenditure data which may be queried with the account type.
Initially, a user or application will submit a secure and encrypted request with a valid username and password to the Get Token - Authentication endpoint. 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 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 endpoint. 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 API leverages SSL to securely and efficiently authenticate users and applications, and to issue a short-lived token. Subsequently, this token can be used to make API Web services requests 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.
The APIs for Flex and Silverlight also have class methods to request tokens. These methods are actually wrappers around the Get Token service.
A API account can be set up with a "geofence" constraint which geographically limits the geography data layers which may be accessed through the API subscription account. The GeofenceInfo service can be leveraged to query the API for the geographic features/areas that may be accessed through the account. See Geofence Overview and Geofence Info for more information.
| Geofence Info | Obtain a list of geographic features from the analysis data layers accessible from the current user account. |
|---|---|
| Get Token | Securely request a short-lived token with valid API credentials in order to use the API Services and Web SDKs. |
HTTP is the underlying transport protocol for making requests and responses over the Internet. With respect to the APIs, there are two methods that concern us: HTTP GET and HTTP POST.
An HTTP GET request retrieves data from a server using values passed in a URL string. It also includes a set of HTTP headers. Submitting a URL with parameters through a Web browser's URL field is an example of making an HTTP GET request. In the context of REST services, this URL string will include all of the required parameters for a given REST endpoint.
An HTTP POST request sends encoded data to a web server. The Web server is designated by the Web address and, instead of including all of the data (parameters and their associated values) in the URL string, an HTTP POST requests includes it in binary-encoded data that follows the request headers.
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 also security issues, including those associated with the caching behavior of URL strings, in certain client applications such as browsers. Because of this, HTTP POST 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 endpoint with your API credentials unless you can guarantee that the client application will not reveal your API credentials to the end user. This is because users can employ "sniffer" tools to view the outgoing and incoming HTTP traffic. Users may also have the technical knowledge, skills, and tools to view or "decompile" application code that may reveal your API credentials. In general, please be aware of these issues and take the necessary precautions to protect your credentials and investment.
There are basically two main concepts to the token-based security scheme employed by the REST and SOAP services and APIs for Flex and Silverlight:
Token parameter value in the API services and APIs for Flex and Silverlight.