Authenticate your API user

Congratulations, you're ready to use the Volt API!

The first thing you'll need to do is use your client and API user credentials to authenticate. Volt uses the oAuth2.0 standard for authentication.

Prerequisites

You'll need to know the Client ID and Client Secret, supplied when you registered your application and the API Username and password.

If you don't have them yet, head over to Fuzebox now.

Generating an access token

Access to the Volt API is controlled by the use of tokens, which you'll need to supply in your HTTP headers when you make an API request.

To generate an access token, you first need to authenticate, which you can do by sending a POST request to the /oauth API endpoint and providing the following information.

Request location

Sandbox

POST https://api.sandbox.volt.io/oauth

Production

POST https://api.volt.io/oauth

Request headers

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

Request form parameters

client_id - the Client ID for your application

client_secret - the Client Secret you retrieved

username - your API user name

password - your API user password

grant_type - should be set to password

Once you've successfully authenticated, you'll be returned an access_token and refresh_token in the response, which you'll then use as authorisation for your subsequent API calls.

Response example

{

"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0",

"token_type": "bearer",

"expires_in": 3600,

"refresh_token": "Gbw1WY4V2LvozcwRHdoJiOiM3cpJye.9JCVXpkI6ICc5RnIsIiN1IzUIJiOicGbhJye0nN5EjM3gDO1QTM6ICc4VmIsYTO3UDO3gTN0EjOiQXYpJCLiMjMx8lczVnI6IiY1NnIsIyLxY3LyFGZuFGbhN2Lt92YuUGbw1WY4VmLpBXYv8iOzBHd0hmI6ICZ1FmIsIyLt92YuADa0VXYuU"

}

Using your access_token

Note that your access_token is only valid for one hour from the point you authenticate. Please ensure you store your refresh_token if you'll be accessing the Volt API for longer than this, because you can use it to obtain a new access_token as required.

To access the rest of the Volt API you'll need to send your access_token in an HTTP header called Authorization (noting the American spelling!), which uses the format "Bearer {access_token}"

Example Authorization header

Using the access_token example above, the contents of your Authorization header should look like this

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0

Refreshing your token

For security reasons, your access token is only valid for one hour. Refresh tokens are valid for much longer but do eventually expire.

If your application needs to access the API beyond the lifetime of the access_token, you can use the refresh_token we supplied to obtain a new access_token, which you can do by POSTing to the same /oauth endpoint, providing the following information.

• grant_type - should be set to refresh_token
• refresh_token - will be the contents of the refresh_token we supplied during the initial authentication

You'll then receive a new access_token and updated refresh_token in the response. Use the new access_token to access the API from now on.

Refresh token expired?

If your refresh_token has expired, you can simply authenticate again to get a new set of tokens.