OAuth 2.0 protocol

Onecub Connect uses the OAuth 2.0 protocol for authentication and authorization.

This page gives an overview of the OAuth 2.0 authorization scenarios that Onecub Connect supports.
For more details about using OAuth 2.0, see the RFC.

So far only the Authorization Code grant type is supported by Onecub Connect.

Workflow

This is the general workflow that you will have to follow in order to communicate with Onecub Connect.

Get user authorization

Step 1: Redirect user

First you'll need to redirect your user to the authorize endpoint where he will be able to authorize access to his data.

Note
We provide for you an auto-configured button that allows to skip this step during your implementation.

URL: https://connect.onecub.com/OAuth/Authorize
Method: GET
Parameters Description Requirement
client_id ID we gave you when you signed up required
redirect_uri The redirect_uri you provided when you signed up, Onecub will redirect users to this URL after they authorize access to their data required
response_type Must be equal to code since this is the authorization code grant type required
state An opaque value used to maintain state between the request and the callback. You should use it to prevent cross-site request forgery strongly recommended

Request sample (with line breaks and spaces for readability)

https://connect.onecub.com/OAuth/Authorize?
  client_id=myclientid12345&
  redirect_uri=https://example.com/oauth/callback&
  response_type=code&
  state=XYZ

Once the user authorizes access, he is redirected back to the redirect_uri you specified.
An authorization code is appended to the redirect_uri as shown below:

https://example.com/oauth/callback?code=6b8db6...&state=XYZ

If you provided a state, it is propagated to the redirect_uri, you can then test if this is indeed the one you sent.

Note
If the user denied the access to his data, he will still be redirected to your redirect_uri but no code will be appended.


Step 2: Exchange authorization code for access token

Now that you have the authorization code, you need to exchange it for an access token. To do so you are going to have to use the token endpoint.

Notes
- You don't have to pass an authorization header to access this request. But if you don't, you'll have to send your ID and Secret in clear in the request body.
- The code can be exchanged for 5 minutes after its generation. After that you'll have to redirect your user to the authorize endpoint again to get a new one.

URL: https://connect.onecub.com/OAuth/Token
Method: POST
Authorization: Basic/None
Parameters Description Requirement
client_id ID we gave you when you signed up optional (required if No Auth)
client_secret Secret we gave you when you signed up optional (required if No Auth)
redirect_uri The redirect_uri you provided when you signed up required
grant_type Must be equal to authorization_code since this is the authorization code grant type required
code The authorization code returned from the initial request required

Request sample
  header:
    Authorization: Basic WjJ4NVdtTnNhSHA2Sm1RO...
    Content-Type: application/x-www-form-urlencoded
  body:
    redirect_uri: https://example.com/oauth/callback
    grant_type: authorization_code
    code: 6b8db6...

Note
The Basic authorization header is generated through a Base64 encoding of client_id:client_secret (see the RFC).

Token endpoint response
Parameters Description
access_token Access token that you can use to proceed calls to the Onecub Connect API.
The access token has a lifetime of 20 minutes
token_type Identifies the type of token returned. At this time, this field will always have the value bearer
expires_in The lifetime of the access token in seconds
refresh_token Refresh token that you can use to acquire a new access token after the current one expires.
The refresh token has a lifetime of 6 months

Response sample
{
    access_token: RnAIe-rx7zOby...,
    token_type: bearer,
    expires_in: 1199,
    refresh_token: fLi7UfPIGcHVD8...,
}

Important
You should store the refresh token for future use. You will need to provide the refresh token to get a new access token when it expires or to proceed an access revocation.


Step 3: Use refresh token to get a new access token

After your access token expires, you can use your refresh token to get a new one through the token endpoint.

URL: https://connect.onecub.com/OAuth/Token
Method: POST
Authorization: Basic/None
Parameters Description Requirement
client_id Your ID provided when you signed up optional (required if No Auth)
client_secret Your Secret provided when you signed up optional (required if No Auth)
grant_type Must be equal to refresh_token required
refresh_token Your refresh token required

Request sample
  header:
    Authorization: Basic WjJ4NVdtTnNhSHA2Sm1RO...
    Content-Type: application/x-www-form-urlencoded
  body:
    grant_type: refresh_token
    refresh_token: fLi7UfPIGcHVD8...

If your refresh token is still valid, the Onecub Connect authorization server will send you a new access token and a new refresh token.
If not, the authorization server will respond with a 400 Bad Request code.

Response sample
{
    access_token: R7-CndHDV65diU2...,
    token_type: bearer,
    expires_in: 1199,
    refresh_token: Wlneb29BQiKdmR...,
}

Your old refresh token (here fLi7UfPIGcHVD8...) can't be used anymore.
In your future requests you must use the new one that is sent to you in the response : Wlneb29BQiKdmR...

Since this is a new refresh token you have 6 months to use it before it expires.

Note
If your refresh token expires (meaning you didn't refresh your tokens during 6 months), you must redirect your user again to the authorize endpoint so he can reauthorize access to his data.

Access revocation

At any moment, the user can revoke your access to his data through the Onecub data sharing center.
If he does, you will not be able to use your access token to make API calls and you won't be able to request a new access token with the refresh token either.

Important
In order to comply by Onecub's privacy principle as well as the EU Data Protection Regulation, it is mandatory for you to include a revocation link in your service.

To perform an access revocation you have access to the revocation endpoint on which you have to send your refresh token.
This way, all your accesses to the user's data will be revoked.

To get back the access to the user's data after an access revocation, you will have to redirect him again to the authorize endpoint so he can reauthorize access to his data.

URL: https://connect.onecub.com/OAuth/Revoke
Method: POST
Authorization: Basic
Parameters Description Requirement
token The token to revoke required
token_type_hint The type of the token to revoke. The Onecub Connect authorization server only allows refresh_token revocation optional

Request sample
  header:
    Authorization: Basic WjJ4NVdtTnNhSHA2Sm1RO...
  body:
    token: fLi7UfPIGcHVD8...

Note
The Basic authorization header is generated through a Base64 encoding of client_id:client_secret (see the RFC).

The request will send you back an HTTP code to attest that the request went well or not.
For security purpose, you will get an OK (200) response even if you pass a wrong token.