Welcome to API Hubic OAuth2 sandbox

In hubic API, we choose to use the OAuth 2.0 Authorization Framework, as defined in RFC6749. This sandbox is provided to developers who need to understand the OAuth2 server-side flow in order to make great applications using Hubic.

This sandbox has been built like any other third-party application which want to use hubic API. No more, no less.

If you follow the different steps in this documentation, you will fully understand the server-side authentication flow on Hubic API.

Just start to register your app in your hubic account manager.

You will receive a credential with your client id and your client password

We did it for this sandbox application, and we received those credentials :

client_id client_secret
{{client_id}} {{client_secret}}


In this first step, you need to choose scope needed to use your app

First, you need to know how scope works. A scope is always defined by a perimeter, and a right on this perimeter. Rights are linked to HTTP method that you will have to use on our API. See this tab to understand this link :

HTTP method GET PUT POST DELETE
Hubic API r w w d

Those rights can be applied on different perimeters. For some evident reasons, all perimeters does not allow all rights. Choose perimeters needed for your application :

/{{p.name}}
{{right.value}} {{right.text}}

This will give you a valid "scope" parameter : {{scope()}}

Now that your scope is defined, you can redirect user to this URL with GET method to get a request token :

{{auth_url}}
client_id={{client_id}}
&redirect_uri={{redirect_uri}}
&scope={{scope()}}
&response_type=code
&state={{state}}

Warning! To avoid some strange issues, you need to URL encode your redirect uri.

{{ne_redirect_uri}} {{redirect_uri}}
Get request token

Oops, an error occured

This first GET request can sometimes goes into error state. User can refuse to give you access, or your scope can be malformed. When this kind of error happened, our login application will redirect user to your application with two parameters in the URL : error, and error_description. You can find a full description of all different errors :

Please complete step 1 before step 2

Good ! Look at our url, there is some interesting parameters :

Code {{code}}
Scope {{scope}}
State {{state}}

It is time to convert our credentials into Base64 :

Credentials :
{{client_id}}:{{client_secret}}

Base64 : {{client_base64}}

And create a POST request :

POST {{token_url}} HTTP/1.1
Authorization: Basic {{client_base64}}


code={{code}}
&redirect_uri={{ne_redirect_uri}}
&grant_type=authorization_code

Warning! API Hubic only support application/x-www-form-urlencoded, so do not try to send application/json data in your POST request

You don't have to redirect user to this URL. Just use Javascript, for example, to make an HTTP POST request. This request will return you a JSON formated response.



Oops, an error occured
error : {{error}}
error_description : {{error_description}}

When making your POST request to exchange your request code for an access token, something wrong can happen. Instead of an access token, you can receive a JSON formated response with error and error_description parameters. You need to handle those errors.

Please complete step 2 before step 3

Well done, you have now an access token to call API Urls. This access token allows you to use method in the scope finally given by user. As we said before, the POST request give you a JSON formated response, with all data needed to use the access token.

access_token {{access_token}}
expires_in {{expires_in}}
refresh_token {{refresh_token}}
token_type {{token_type}}

You can store those data, and make your first call on hubic API ! Just ask the correct url and method according to your needs, and pass your access_token in the HTTP Authorization header, with the keyword Bearer

GET {{account_url}} HTTP/1.1
Authorization: Bearer {{access_token}}



email {{email}}
creationDate {{creationDate}}
status {{status}}
firstname {{firstname}}
lastname {{lastname}}

But after a delimited time ({{expires_in}} milliseconds), you will need to refresh your token ...



Oops, an error occured
error : {{error}}
error_description : {{error_description}}

When you call API, you can miss your call, or an error can occured. You need to handle all of those errors.

Please complete step 2 before step 4

Refreshing an access token looks like getting a new one, but some parameter's values change.

First, you need to authenticate your application, with Authorization: Basic header or passing your credentials (client_id, client_secret) in POST data. Remember, we only support application/x-www-form-urlencoded POST data.

POST {{token_url}} HTTP/1.1
Authorization: Basic {{client_base64}}


refresh_token={{refresh_token}}
&grant_type=refresh_token


With this request, you receive a new acces token :

access_token {{access_token}}
expires_in {{expires_in}}
token_type {{token_type}}
Oops, an error occured
error : {{error}}
error_description : {{error_description}}

As usual, refreshing a token can result to some errors. Here is the complete list :