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 (Optional): Obtaining An Authorization Code
If you are planing to use the Watchlist APIs, you will be accessing InsideView for Sales users data. In order to do so, you need to obtain an authorization code to generate an access token (see next step) via "code" grant rather than via "credential" grant.
This option is only available to you if your API key have been setup with some specific options, like a link to an InsideView for Sales account. If you want to have your API key setup to access the Watchlist APIs, please contact InsideView suport by openig a ticket at https://my.insideview.com/iv/getSupportCommunity.do.
In order to obtain an authorization code, you need to be an InsideView for Sales administrator.
To start the flow to obtain an authorization code, open the following url in a browser: https://login.insideview.com/Auth/login/authorize.iv?clientId=&prompt=admin_consent
At the end of the flow, you will receive a JSON message from which you can copy the authorization code.
Step 3: 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.
- 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 4: Utilizing the Access Token
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.
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.