Home » Vinsight API  »  API Authentication

API Authentication

Overview

Currently our API uses Basic authentication over SSL. Be sure to always send your requests using HTTPS because while we will reject or redirect any HTTP calls to HTTPS, your call will have sent your credentials in plain text for anyone listening to be able to intercept.

To authenticate you can either use an API key or Session cookies, which once you have authenticated, you will have to send these cookies with each subsequent request.

A basic workflow for the API when using Session Cookies to authenticate is to POST your credentials to our Login endpoint, save any returned cookies, then send those cookies for your next calls to the endpoint where you want to view or update data.

The following example uses cURL which can be installed on Windows (using cygwin), Mac (installed by default) or indeed any *nix installation (yum install curl or sudo apt-get install curl).

1. Authenticating via API Keys

To get an API key go to 'Users' on the Settings >  SetUp menu.  Select the 'API Access' tab and then click "Issue New API Key"

 

APIAccess

 

An API Key will be issued that you can then use to access the API without logging on.

Simply include  '?api-key=[insert key here]' at the end of the url to do this.  An example url seeking access to json formatted Sales Orders is set out below:

 

https://app.vinsight.net/SalesOrders.json?api-key=0123456789abcdef9876543210fedcba

2. Authenticating using Cookies

POST to the LoginContext endpoint using your email address as username and your password, --data "" implies a post or you could send your credentials in the body of the post using --data "username=youremail%40yourdomain.com&password=yourpassword". Store any returned cookies in the file tempcookie.txt and accept json as a result.

curl -u youremail%40yourdomain.com:yourpassword --data "" --cookie-jar tempcookies.txt https://app.vinsight.net/LoginContexts?accept-types=json

2. Making requests

GET entities from the Vessels endpoint in json format, making sure to send cookies from the tempcookies.txt file and same them to vessels.txt. Even though you have already authenticated sending the credentials (-u youremail%40yourdomain.com:yourpassword) with each call makes it unambiguous that you are doing an API call meaning that any errors should come back as text rather than html.

curl -u youremail%40yourdomain.com:yourpassword --output vessels.txt --cookie tempcookies.txt https://app.vinsight.net/Vessels?accept-types=json

>> Extra Help