Authenticating your API user

To get started, you need to use your client and API user credentials to authenticate. We use oAuth2.0 standard for authentication, which is the industry-standard protocol. 

For this step, you’ll need the API username, password, Client ID and Client Secret you received when you first registered your application. Don’t have them? No problem, you can get them from Fuzebox now. 

We use tokens to control access to our API, and you’ll supply these in your HTTP headers when making an API request. There are three aspects to using tokens: 

  • Generating a token
  • Using the token
  • Refreshing the token

Generating an access token

To get started with generating a token, you need to authenticate by sending a POST request to the /oauth API endpoint and provide the following information:

Request location

We recommend using the Sandbox environment for testing the end-to-end process.

  • Sandbox
  • Production
POST https://api.sandbox.volt.io/oauth
POST https://api.volt.io/oauth

Request headers

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Request form parameters

  • client_id: your Client ID
  • client_secret: your Client Secret
  • username: your API username
  • password: your API password
  • grant_type: should be set to password

This will complete your authentication and you’ll be provided access_token and refresh_token, which will authenticate you in future API calls.

Using your access token

An access_token is valid for one hour once authenticated. Your refresh_token will allow you to obtain a new one, so we recommend keeping the refresh_token somewhere safe if you’ll need to access the Volt API for longer than an hour.

To access our API, you’ll need to send the access_token in an HTTP header called “Authorization” in the format “Bearer {access_token}”. Note that Authorization must be spelled as written here, with American spelling. Authorisation will not be recognised. 

Using the example above, the Authorization header will look like this:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0

Refreshing your token

As noted above, for security reasons an access_token expires after an hour. If your application needs to access our API beyond that hour, you can generate a new one using the refresh_token that you received when you authenticated. To do this, send a POST request to the /token/refresh endpoint with the following:

  • grant_type: should be set to refresh_token
  • refresh_token: will be the contents of the refresh_token you received when you authenticated

You’ll be given a new access_token which will provide access to the API for another hour, as well as an updated refresh_token (you can discard the original refresh_token).

Please note that the refresh_token expires after 24 hours. If you need another, simply repeat the steps for generating an access token.