API

Authentication

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 https://api.virtuoussoftware.com/Token

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 https://api.virtuoussoftware.com/Token

Two-Factor Authentication

When fetching a token for a user with Two-Factor Authentication, you will receive a 202 (Accepted) response stating that a verification code is required.

The user will then need to enter the verification code that was sent to their phone. You will then request the token again but this time you will pass in a OTP (one-time password) header with the verification code received

If the verification code and user credentials are correct, you will receive a token as seen in the Token authentication above.

To request a new Token after the user enters the verification code, add a OTP header:

curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD&otp=YOUR_OTP" -X POST https://api.virtuoussoftware.com/Token