Home » Vinsight API  »  API Authentication

API Authentication


Currently our API uses API keys that you can issue from within the app but in the app, you can also use Basic authentication over SSL if you prefer. 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.

API keys are much easier to use as you just need to include your API key in the query string of your request.

However if you prefer basic auth then 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"




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:



NB: API keys are just special types of users, so if you are on a subscription that supports user permissions then by default an API key will have no permission to do anything, so you MUST remember to edit the API user after creation and add it to a suitable user role with suitable permissions eg "SalesReps" etc.

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