Partner API

Authorization

Requests to the Partner API requires authorization; that is, the user must have granted permission for a partner application to access the requested data. To prove that the user has granted permission, the request header sent by the application must include a valid access token.

1. Your request to retrieve an access token

Using your unique Client Id and Client Secret you call the token service to retrieve an access token. The call is made towards the /token endpoint:

POST https://backend.roaring.io/auth/token

The header of this POST request must contain the following parameter:

HEADER PARAMETER	VALUE
Content-Type	Required. Shall be set to application/x-www-form-urlencoded

The body of this POST request must contain the following parameters:

REQUEST BODY PARAMETER	VALUE
grant_type	Required. Shall be set to "password" or "refresh_token"
username	Required. Your user email you use to login to app.roaring.io i.e username@roaring.io
password	Required. Your user password you to login to app.roaring.io
client_id	Required. As mentioned above. Fetch your unique client_id from integration page
client_secret	Required. As mentioned above. Fetch your client_secret from integration page
refresh_token	Required. If grant_type is set to "refresh_token"

2. Retrieve an access token from the response

On success, the response from the /token endpoint has the status code 200 OK in the response header, and the following JSON data in the response body:

KEY		VALUE DESCRIPTION
access_token	string	An access token to be used in subsequent calls to the Partner API.
refresh_token	string	The refresh token, which can be used to obtain new access tokens using the grant_type "refresh_token"
token_type	string	How the access_token may be used, always "Bearer".
expires_in	int	The time period (in seconds) for which the access token is valid.

An example request and response to the token endpoint will look something like this:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=<username>&password=<password>&client_id=<client_id>&client_secret=<client_secret>" https://backend.roaring.io/auth/token

{
  "access_token": "asdfg...xzy", 
  "refresh_token": "zxcvv...abc", 
  "token_type": "Bearer", 
  "expires_in": 3600
}

3. Use the access token to access the Partner API

The access token allows you to make requests to the Partner API.

The header of this request must contain the following parameter:

HEADER PARAMETER	VALUE
Accept	Required. Shall be set to "application/json" or "text/html" in order to get the html experience. "text/html" is not recommended in development mode. It should only be in use for navigation purpose in HATEOAS
Authorization	Required. Shall contain your access_token with Bearer as prefix

An example of how access token allows you to make requests to the Partner API.

$ curl -H "Authorization: Bearer XXXX...zzzzz" -H "Accept: application/json" "https://backend.roaring.io/"
{
  "name": "root",
     "properties": {
         "loggedInUser": {
             "id": "<id_of_logged_in_user>",
              "email": "username@roaring.io",
              "firstName": "First name",
              "lastName": "Last name",
              "details": {
                 "language": "sv"
              },
              "createdAt": "2019-11-07T17:59:07Z",
              "updatedAt": "2019-11-07T17:59:07Z",
              "hash": "aabbcc... xxyz",
              "ip": "<ip_of_logged_in>"
          },
          "clientVersion": "1.4.13"
     }
}

Your access token is valid for one hour, so you need to handle the error from an expired token and request a new one when needed. Please read more about OAuth2 authorization framework here.

4. Use refresh token

Your refresh token is valid for 30 days. Please read more about refresh token in OAuth2 authorization framework here.

An example request and response to the token endpoint will look something like this:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<client_secret>" https://backend.roaring.io/auth/token

{
  "access_token": "asdfg...xzy", 
  "refresh_token": "zxcvv...abc", 
  "token_type": "Bearer", 
  "expires_in": 3600
}

HATEOAS

The Partner API is powered by HATEOAS architecture. HATEOAS guides you through the interface by offering control alongside the data.

HATEOAS or Hypermedia As The Engine Of Application State is a REST API architecture where the client interacts with a REST API entirely through the responses provided dynamically by the server. This means that you shouldn't need any documentation or out-of-band information to use the API. One of the distinguishing features of the HATEOAS API architecture is the idea that the responses themselves tell you what you can do and how you can do it.

This is done by including information in the response on what endpoints that are available, how the requests to these endpoints should be structured and what responses to expect.

In order to familiarize more with the HATEOAS guide, go to https://backend.roaring.io/ with your internet browser.