Authentication

Octopia APIs are protected and provide access control by using authentication and authorization features.

The authorization framework used is OAuth 2.0. It gives an API client limited access to an API. The API client obtains access through a token.

Token is used by the clients when they communicate with the API. He must be filled into each request header to securise the communication with SSL protocol (HTTPS). This authentication scheme uses a JWT Token.

In order to generate a token the client needs API credentials which are composed by clientId and clientSecret.
These credentials are provided by Octopia teams after signature of contract.

The token will expire every 5 minutes. It will then be necessary to obtain a new one by refreshing it.

Retrieve a first 'access token'

The principle is based on requesting a specific URL. This token authenticates the client and authorizes him to do actions.

In order to retrieve tour token you must do a HTTP POST request on the URL :

https://auth.octopia-io.net/auth/realms/maas/protocol/openid-connect/token

by passing the parameters in form-urlencoded format

      grant_type : have to be set with "client_credentials"
      client_id : your client id
      client_secret : your client secret

Example :

Request

curl -X POST "https://auth.octopia-io.net/auth/realms/maas/protocol/openid-connect/token"
-H "accept: application/json"
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret"

If the request have a success result, you should retrieve the access token in the response body

Response

{    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJZZ1N0dWFGTDV6NUh2QlRaZ3huRVNWaS1QYlA4T183aUx5R2g3MzY1M1dBIn0.eyJqdGkiOiJhZDg0MTFmZS01MGM0LTQ5NjItYTc2NS1mOTIwZTIxMTU4M2MiLCJleHAiOjE2MTQxODUyMjYsIm5iZiI6MCwiaWF0IjoxNjE0MTg0OTI2LCJpc3MiOiJodHRwczovL29hdXRoMi5jZGlzY291bnQuY29tL2F1dGgvcmVhbG1zL21",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1NjhiNWRiZi1kNmZiLTQ4NTgtYjU4MS1lNDhjODE1MzY0OWMifQ.eyJqdGkiOiJmMWRkM2Q2NS1iZGFjLTRhMzktOTdhMS0yNDRmMWQyMDIzMTkiLCJleHAiOjE2MTQxODY3MjYsIm5iZiI6MCwiaWF0IjoxNjE0MTg0OTI2LCJpc3MiOiJodHRwczovL29hdXRoMi5jZGlzY291bnQuY29tL2F1dGgvcmVhbG1zL21hYXMtaW50",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "29e9ad0a-1bf4-48b8-941c-c82a929574c6",
    "scope": ""
}

Renew an 'access_token'

As the validity of the 'access_token' expires every 5 minutes you must renew it in order to continue using the Octopia API

2 possibilities to renew a 'access token' :

1) Generate a new 'access_token' using API credentials (cleintid and clientsecret)

2) Generate a new 'access_token' using 'refresh_token'

Why using a refresh token?

refresh_token allows the client to retrieve access token without API credentials during 30 minutes.

For example, if the client would like to authorize temporary and safely a partner to have access to API octopia on behalf him (without giving API credentials)

How to retrieve a refresh_token ?

As for retrieval of the access token (with credentials), this method consists in making a POST HTTP request on the same URL

https://auth.octopia-io.net/auth/realms/maas/protocol/openid-connect/token

These are the parameters that differ

      grant_type : have to be set with "refresh_token"
      refreh_token: the refresh token retrieve from the previous call

Example :

curl -X POST "https://auth.octopia-io.net/auth/realms/maas/protocol/openid-connect/token"
-H "accept: application/json"
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1NjhiNWRiZi1kNmZiLTQ4NTgtYjU4MS1lNDhjODE1MzY0OWMifQ.eyJqdGkiOiJmMWRkM2Q2NS1iZGFjLTRhMzktOTdhMS0yNDRmMWQyMDIzMTkiLCJleHAiOjE2MTQxODY3MjYsIm5iZiI6MCwiaWF0IjoxNjE0MTg0OTI2LCJpc3MiOiJodHRwczovL29hdXRoMi5jZGlzY291bnQuY29tL2F1dGgvcmVhbG1zL21hYXMtaW50"

If the request have a success result you should retrieve the access token in the response body (the same as retrieve your access token)

Postman

In order tout test these calls we advice you to use Postman client API.
You can download the desktop app or use the online web version

Once Postman is ready for use, download the collection and import it into Postman workspace.

ImportCollection

Then you have to configure the variables of the collection setting your client_id and your client_secret.
To do it select the Edit menu option

Configure collection


Make the changes in Variable section setting the values in initial value column.
Don't forget to save the settings.

Picture


Now you can execute the requests. 
First execute the Retrieve token request if ou have a successful response you can then execute the Refresh token one.

Picture