Learn how to authenticate with the Virtuous API. Once you have got a token you can start calling any of our APIs.

Authentication Types

There are 2 authentication methods for the API:

  1. OAuth Token authentication (Recommended)
  2. HMAC Authentication (Not recommended as its very limited in how it can interact with the API).

The easiest way to authenticate is using OAuth Token authentication. Upon requesting a token you will get back a json response with a access_token that will be used going forward along with a refresh token to fetch a new token when the original expires in 2 weeks.

Create a Token

The email address and password need to be url encoded prior to the string construction to allow any special characters that may be present in your password.

Here is a quick example that shows how to request a token using curl:

curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD" -X POST

Any future requests to the API will need to include the following header:

Authorization: Bearer access_token

Refresh Tokens

When fetching a token, a refresh token will also be returned. This should be stored and used to fetch new tokens whenever your token expires.

To request a new Token use the refresh_token from your original Token response as follows:

curl -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN" -X POST