Introduction
The InsideView APIs are typically secured using an OAuth 2.0 flow.
There are multiple steps in the process, culminating in successful round trips to retrieve data from the API server. These will be described sequentially.
Step 1: Obtaining a Client ID and Client Secret
After executing the API License Agreement with InsideView, your organization will be issued an API Key (a client ID and a client secret). Both the client ID and the client secret are randomly generated. As may be obvious from the name, the client secret should be protected by your organization. In fact, it should be part of your server configuration and not be allowed into other contexts. For your responsibilities under your license with InsideView for protecting your client secret, please refer to your API License Agreement.
If you don't have an API key and would like to test our APIs, please contact your Account Executive. If you are not an InsideView customer, use the contact us page from our corporate web site to initiate the process.
The client ID, while obscure and randomly generated, can be passed around in an unsecured fashion to refer to your account without concern, since it is useless without the corresponding client secret. Because it is obscure and randomly generated, a more human-friendly account name can also be used to refer to the client ID and client secret combination.
Step 2: Generating Access Tokens
The client ID and client secret are not directly used to access the data provided through the APIs. Instead, they are used to generate a valid access token, and the access token is then used to make API requests.
Access tokens should also be protected, but they have two properties that makes them suitable for issuance to your client applications, such as a mobile device, a JavaScript web application, or for use in server-to-server communications:
- The access tokens are designed to be independently revocable. This means that if an access token is compromised, that the access token can be revoked without affecting other access tokens. By contrast, if the client secret were compromised, and needed to be revoked, this would affect all of the account’s access tokens simultaneously.
- Each access token is associated with a throttling limit. The throttling limit is designed to protect the InsideView servers from excessive load, and to protect your account from over-utilization.
Together, these properties mean that your organization is in control of how many access tokens it issues and thereby has a significant measure of control over your total API utilization.
See New Token endpoint for more details.
Step 3: Utilizing the Access Token
After your server has used its client id and client secret combination to generate an access token, it (or your mobile or JavaScript client) then uses the access token to access data from the InsideView API.
Every HTTP request (GET, POST, PUT or DELETE) to the InsideView API is authenticated and authorized using the access token.
Approach to and possible exceedance of the access token’s throttling limit is regularly checked by InsideView's throttling system. If an access token’s throttling limit is exceeded, usage of that access token will be locked out for a throttling time period.
See the Throttling and Quota Monitoring article for details regarding warnings, exceedances and lockouts from the API.
Step 4: Revoking the Access Token
Access token revocation is forthcoming. It is not yet part of the product.
Summary
The authentication flow described above is expected to be versatile enough to serve most customers of the 1.0 product.
Future product features may require more complex authentication flows. Also some customers may want SAML 1, SAML 2 or other federated authentication mechanisms to be supported. These flows are already supported by the InsideView federated authentication service, but use of them requires an InsideView solutions architect to configure the service on a per-partner basis, and is outside the scope of this overview.