Authentication

OAuth 2.0

The hubiC API uses OAuth 2, a well-known standard to authenticate and authorize users. As a starting point, we suggest taking some time to read the official OAuth 2 RFC. OAuth also allows third-party applications to perform some requests according to a defined perimeter (scope), after getting the user approval.

The hubiC API offers two different flows for third-party applications, as defined in OAuth 2 RFC:

But before talking about the flows, it is important to fully understand the scope parameter.

Scope

When working on an application that using the hubiC API, you first need to define the scope of your application.

If you look at the hubiC API Console, you will see different entry points: /account, /links...
Your application can use any of those entry points, according to your needs.

Once the entry points are defined, you have to choose the HTTP method you need to perform on each entry points. For example, if your application needs to see all published links, you must ask for the /links entry point. And as you want to get the links, you also ask the scope for the HTTP GET method on /links.

For each HTTP method that can be used on hubiC API, we defined a one-char equivalent:

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

When you have defined the entry point and the HTTP method needed for your application, you just have to concatenate them with a '.' char to create a valid scope. In order to perform a HTTP GET on /links, you will have to ask for the links.r scope.

If you need multiple entry points, just combine them with the ',' char: account.r,links.r.

Each entry point does not allow all of the HTTP methods. Please refer to this table to see the possible combinations:

/{{p.name}}

{{right.value}} {{right.text}}

For example, here is a complete scope for all methods on hubiC API:

account.r,links.rw,usage.r,credentials.r,apps.rd

As you probably seen if you tried the hubiC API Console or Sandbox, the user can decide to refuse some of the scopes asked. This is why it is really important to define a scope with no more than your needs, and probably take time to explain to user why you need this specific scope.

Server-side flow

Also known as the web server flow, this flow is intended to be used by server-side applications. Using this flow give you a long-lived access to user's account. At the end of this flow, you will receive an access_token and a refresh_token which allow you to request on hubiC API until the user revokes your access. With this flow, you will be able to use the API even if the user is offline. It is the recommended flow to give the best user experience.

In order to give you a full understanding of the web server flow, we created this sandbox to see OAuth 2 in action. Feel free to use it!

Server-side flow is a three steps flow:

  1. Get request code
  2. Get access token
  3. Refresh access token

Get request code

In this step, called Authorization request, the final user will have to login on our login webpage, hosted on hubic.com servers. You have to redirect the user to the hubiC OAuth Authorization endpoint.

https://api.hubic.com/oauth/auth

To make it work, you need to add some parameters in the HTTP redirection request:

client_id
required
Your client id, obtained when registering your application.
client_id=api_hubic_1234567AzErTyUiOpQsDfGh
redirect_uri
required
The HTTPS URI where user will be redirected after login. This URI needs to belong to the domain you saved when registered your application. This URI needs to be url encoded.
redirect_uri=https%3A%2F%2Fwww.yourredirecturl.com%2Foauth
response_type
required
In the server-side flow, this parameter MUST be set to code.
response_type=code
scope
recommended
The scope needed by your application. See the Understanding scope part to understand the scope parameter. When not set, default value is account.r.
scope=account.r,links.rw
state
recommended
A random string you choose that will be added in the response
state=ThisIsARandomString

At this point, the user is redirected to our login webpage. The user has to log in, and Allow or Deny your application.

Handling the response

If the user decides to Allow your application, he is redirected to the URI previously given with some added parameters:

https://www.yourredirecturl.com/oauth?code=123456ABCDEFGH&scope=account.r,links.rw&state=ThisIsARandomString

The code parameter, also known as Authorization code, is a unique code that allows you to ask for an access_token. It is a short-lived code that expires after five minutes. It is also a disposable code that can be used only once.

The scope parameter is the final scope the user grants to your application.

This parameter exposes the scope accepted by the user, and is not always the scope you asked for. The user can decide the final scope. You need to handle the case where the user declines parts of the scope, and explain him why you need those scope.

The state parameter is the same random string you sent in the previous request.

Handling error

If user decide to Deny your application, or if an error occurs, the user is redirected to the URI previously given, with an error parameter:

https://www.yourredirecturl.com/oauth?error=access_denied&error_description=refused&state=ThisIsARandomString

You have to handle errors, and tell the user if something wrong happened. Here is the complete list of errors:

Get access token

Now that you have your Authorization code, you will have to exchange it before its expiration for an Access Token.

You have to perform a HTTP POST request to the Token endpoint:

https://api.hubic.com/oauth/token

Just give the correct parameters in order to obtain an access token:

code
required
The authorization code you obtained in the previous step.
code=123456ABCDEFGH
redirect_uri
required
The HTTPS URI. This URI needs to belong to the domain you saved when registering your application. This URI needs to be url encoded.
redirect_uri=https%3A%2F%2Fwww.yourredirecturl.com%2Foauth
grant_type
required
In the server-side flow, this parameter MUST be set to authorization_code.
grant_type=authorization_code
client_id
optional
Your client id, obtained when registering your application.
client_id=api_hubic_1234567AzErTyUiOpQsDfGh
client_secret
optional
Your client secret, obtained when registering your application.
client_secret=AbCdEfGhIjKl

When you ask for an access token, you have to authenticate your application. The first step for this is to simply add your client id and client secret in the HTTP POST request, as parameters.

Nevertheless, we recommend instead to use the HTTP Authorization header. In order to use it, you have to combine your client id with your client secret with a ':' char, and encode the result string into Base64.

HTTP Authorization: Basic YXBpX2h1YmljXzEyMzQ1NjdBekVyVHlVaU9wUXNEZkdoOkFiQ2RFZkdoSWpLbA==

Once you have made your HTTP POST request with the right parameters, you will receive a JSON encoded response.

Handling the response
{
    "access_token"       :"987654321gfedcba",
    "expires_in"         :"3600",
    "refresh_token"      :"123456789abcdefg",
    "token_type"         :"Bearer"
}

The access_token is the unique code that allows your application to fetch specific data from hubiC API. It is a short-lived token you to pass with every request to the hubiC API. This code links your application to a specific user, for a defined scope.

After the expires_in time (milliseconds), the access_token will expire.

Once your access_token has expired, you are able to refresh it with the refresh_token. This token is a long-lived token that allows you to get a new access_token. This token never expire, but do not forget that the user can revoke your application at any time.

The token_type is always be set to Bearer.

Now that your application has a valid access token, you can perform method on hubiC API.

Handling errors
The JSON encoded response can be an error response.
{
    "error"              :"invalid_request",
    "error_description"  :"Invalid code",
}

Please handle those errors. Here is the complete list:

Refresh access token

Having an "invalid_token : expired" error when you perform a request means that it is time to refresh your access token. Refreshing a token is possible thanks to the refresh_token. In hubiC API, refreshing a token equals getting a new one. In order to do this, you need to perform a HTTP POST request to the Token endpoint:

https://api.hubic.com/oauth/token

Just set this parameters in the request:

refresh_token
required
The refresh token of the access token that needs to be refreshed
refresh_token=123456789abcdefg
grant_type
required
This parameter MUST be set to refresh_token.
grant_type=refresh_token
client_id
optional
Your client id, obtained when registering your application.
client_id=api_hubic_1234567AzErTyUiOpQsDfGh
client_secret
optional
Your client secret, obtained when registering your application.
client_secret=AbCdEfGhIjKl

In this step, you need to authenticate your application. You can do this by passing client_id and client_secret in the post request, or (recommended) by using the HTTP Authorization header.

HTTP Authorization: Basic YXBpX2h1YmljXzEyMzQ1NjdBekVyVHlVaU9wUXNEZkdoOkFiQ2RFZkdoSWpLbA==

Handling the response

A JSON encoded response is returned with a new access token:

{
    "access_token"       :"1112131415poiuytre",
    "expires_in"         :"3600",
    "token_type"         :"Bearer"
}

Note that you don't receive a new refresh token: you keep the same. You now have a new access token to perform requests with the hubiC API. Your old access token is not valid anymore.

Handling errors

Obviously, your HTTP POST request can result with a JSON encoded error response that you need to handle:

Implicit grant flow

For some specific applications, you may need a quick access to the hubiC API. You don't want to bother with request code. This is the main goal of the implicit grant flow. Getting an access token is relatively complex, and you will need your application credentials (client_id and client_secret) to get the token. But if you decide to develop, for example, a javascript-only application, you have to expose your credentials, which is not a good idea. For this specific need, the hubiC API allows you to get a short-lived access token that cannot be refreshed. This token allow your application to perform methods with the hubiC API for a specific time. With this flow, the user needs to be online in order to authenticate again if the access token expires. Use this flow only if it seems essential to your application.

Implicit grant flow is a one-step flow, easy to use, but it won't give you a long-lived access to user account.

Get access token

Using the implicit grant flow to get an access token requires only one HTTP redirection. Redirect the user to the hubiC API Authorization endpoint:

https://api.hubic.com/oauth/auth

To make it work, you have to give some parameters in the HTTP redirection request:

client_id
required
Your client id, obtained when registering your application.
client_id=api_hubic_1234567AzErTyUiOpQsDfGh
redirect_uri
required
The HTTPS URI where user will be redirected after login. This URI needs to belong to the domain you saved when registering your application. This URI needs to be url encoded.
redirect_uri=https%3A%2F%2Fwww.yourredirecturl.com%2Foauth
response_type
required
In the implicit grant flow, this parameter MUST be set to token.
response_type=token
scope
recommended
The scope your application needs. See the Scope part to understand the scope parameter. When not set, default value is account.r.
scope=account.r,links.rw
state
recommended
A random string you choose that will be added in the response
state=ThisIsARandomString

At this point, the user is redirected to our login webpage. The user has to log in, and Allow or Deny your application.

Handling the response

If the user decides to Allow your application, he is redirected to the URI previously given with some added parameters in the hash:

https://www.yourredirecturl.com/oauth#access_token=987654321gfedcba&expires_in=3600&token_type=Bearer&scope=account.r,links.rw&state=ThisIsARandomString

The access_token is the unique code that allows your application to fetch specific data from the hubiC API. It is a short-lived token that you have to pass on every request to the hubiC API. This code links your application to a specific user, for a defined scope.

After the expires_in time (milliseconds), the access_token expires.

The token_type is always set to Bearer.

The scope is the final scope accepted by the user.

The state parameter is the same random string you sent in the previous request.

Now that your application has a valid access token, you can perform method on the hubiC API.

Handling errors

If the user decides to Deny your application, or if something bad happens, he is redirected to the URI previously given, with an error parameter in the hash:

https://www.yourredirecturl.com/oauth#error=access_denied&error_description=refused&state=ThisIsARandomString

Please handle those errors. Here is a complete list:

Perform request

By simply passing your Access token with the HTTP Authorization header, you are able to perform methods on the hubiC API.

GET 1.1 https://api.hubic.com/1.0/account
HTTP Authorization: Bearer 987654321gfedcba

Handling the response
All responses from the hubiC API are JSON encoded:
{
    "email"              :"hubic_email@hubic.com",
    "creationDate"       :"2011-11-14T22:40:12+02:00",
    "status"             :"ok"
}

If you want to discover all the different methods allowed on hubiC API, feel free to use the hubiC API Console !

Handling errors

Perform methods on the hubiC API can result to some errors: