Access and Authentication Guide
CloudQuote lets you access data from our data warehouse, in a variety of different formats, include JSON, XML, CSV, and more.
To access our data, your front-end or back-end application can authenticate with the CloudQuote API platform in a variety of different ways.
Accessing the API from Front-End Applications
A front-end application is any application whose code is run by a user, and which retrieves data directly from CloudQuote.
Examples of this type of application would include:
- Websites that retrieve dynamic data in the browser using AJAX, jQuery, etc.
- Web Applications/Single Page Apps (React, Angular, etc)
- Desktop Apps (Native Apps, Metro Apps, etc.)
- Mobile Apps (iOS, Android, etc.)
Since front-end applications are run by the user, CloudQuote operates on the premise that all data within the application is insecure. Since all data in the application is insecure, CloudQuote relies on the application passing through certain identifying information to authenticate the origin of the request, and then uses heuristics to identify patterns of unauthorized access.
For a front end application, the following access methods are supported:
- CORS Request with Origin & Referrer matching a whitelisted domain name, with no application key (Most Common)
- CORS or Non-CORS Request with Public Application Key and OAuth access token
Accessing the API from Back-End Applications
A back-end application is any application whose code is exclusively run on a server, in a private manner, with details such as API keys shielded from public view
Examples of this type of application would include:
- Websites that are rendered on the server using PHP, Java, .NET, ASP, Ruby, NodeJS, etc.
- Scripts that run on the server and database or store data
Since back-end applications are run on the server, CloudQuote operates on the premise that either the code for the application is secure OR that the location of the server that the code runs on is static.
For a back-end application, the following access methods are supported:
- Request with a private application key passed with the request (Most Common)
- Request with a public application key passed with the request, and the IP address of the server is whitelisted (Typical for enterprise apps)
Creating your CloudQuote API Credentials
To create your application keys or to whitelist domain names or IP address for API access, follow these steps:
- Either Log In or Create an Account on CloudQuote, which will give you access to your API Dashboard
- Once you have signed in to the API Dashboard, click "My Account" near the top-right hand corner of the screen
- Click on the API Credentials menu item
- This page will allow you to create various types of access credentials for the CloudQuote API platform.
- See the sections below for details on each type of credential you can create.
Adding a Whitelisted Domain
A whitelisted domain allows a front-end application to access the CloudQuote API, and to make cross-domain requests using CORS.
When using a whitelisted domain to access the CloudQuote API, the following requirements must be satisfied or the request will be rejected:
- The request must include valid CORS headers
- Both the Referer: and Origin: headers must match, and must either match the whitelisted domain exactly, or is a subdomain of the whitelisted domain
- The request must not include any Private Application Keys
- The request must be from a legitimate front-end application - as determined by a heuristic test which compares otherwise valid requests to known patterns of abuse
Adding a Private Application Key
A Private Application Key allows a back-end application to access the CloudQuote API
When using a Private Application Key to access the CloudQuote API, the following requirements must be satisfied or the request will be rejected:
- The request must not include any CORS headers
- The request muse not contain a Referer: or Origin: header
Adding a Public Application Key
A Public Application Key is used together with a secondary authorization mechanism to access the CloudQuote API. The role of a Public Application Key is to identify the application accessing the CloudQuote API, while the secondary authorization mechanism will verify the authorization of the user to use CloudQuote on behalf of the application
When using a Public Application Key to access the CloudQuote API, the following requirements must be satisfied or the request will be rejected:
- The request must include a Public Application Key issued by CloudQuote
- The request must also pass a secondary authorization check (ex. User Key, OAuth, Whitelisted IP Range)
Adding a User Key Check
A User Key Check is a process where a user is given a key by your application, which is passed to the CloudQuote API. Upon first seeing this key, CloudQuote will contact your application to verify that this key is valid. CloudQuote will also contact your application after a certain interval has passed to verify that the key is still valid.
The key can be an OAuth Access Token, JSON Web Token, or any other chunk of information which provides a verifiable authorization of the user to your application.
It is extremely important that the User Key expire after a very short duration, for example 1-5 minutes, to minimize spoofing of requests by a malicious user
Using OAuth (Any Version)
CloudQuote supports and recommends OAuth, but it is up to the application to implement it.
CloudQuote assumes a passive role in the OAuth process, simply forwarding the user key to an endpoint you define, at which point you can verify that the user should be allowed access.
Once an application has generated an OAuth Access Token, it should be passed to the CloudQuote API as a user key, where it will be verified using an endpoint you define.
Adding a Whitelisted IP Address Range
A Whitelisted IP Address Range allows a specific range of host access to the CloudQuote API
When using a Whitelisted IP Address Range to access the CloudQuote API, the following requirements must be satisfied or the request will be rejected:
- The request must also include a Public Application Key
- The Source IP address of the request must be within the range of IPs specified