Authentication Process

Last updated: June 17th, 2019

Authenticate inside Octorate

In these guide will see how sign in inside octorate using APIs. We will do together some flows.

Required knowledge / points:

You MUST have read the start guide carefully.
You should know how HTTP APIs works
It's suggested to be confident with tools like curl

Authentication possible flows

Working with properties/accommodation data

(OAuthLogin)
Access to properties is granular inside Octorate. That means that every user should give you the grant to access their properties. In that case you should use the oauth flow.
When using this authentication method we suppose to receive in header the Bearer token that is generated following the Case 1.

Administrator-alike operations

(ApiLogin)
Sometimes you're application is not accessing existing properties, but you're creating new properties or you're just configuring you api details.
In this case you're allowed to skip the oauth flow and obtain a Bearer token valid for these operations.

1: Working with properties/accommodation data

How's structured your API integration?

Since this API are used from many users, according to the single API Integration strategy in handling the tokens may vary:

Old user of old deprecated APIs This app can migrate old token to newer using migrate endpoint
API User will devel code only for a specific customer Since the refresh token doesn't expire, the developer will do this flow for the customer on the first instance, it will save the refresh token and forget about the authorization phase. (*)
API User will always create new accounts use ApiLogin Security to create all the new accounts. The Refresh token of the OAuthLogin method is inside the response
API User will access data of any property in Octorate In this case, user should notice that someone wants to read/write their data, so it's a requirement to pass inside the authorization step.

* = Even though it's true that it never expires there are some very rare scenarios like a security breach on your app, or the customer that explicitely wants to disconnect and reconnect your app that may result in old refresh token cancellation. Prepare a fallback scenario or give a contact to solve these two cases

Walk-Trough Guide

Octorate API uses the OAuth 2.0 Protocol either for authentication and authorization.
This is a way to obtain authorization to access the resources directly from the user when he's available inside your application.
We do not support other authentication methods.

To begin, your application requests needs an access token. Your application have to redirect the user to our identity WEB page trough a web browser. So we expect you to perform a redirect to this url.

Let's see how the oauth flow is done.

1. Redirect though the browser the user to Octorate Identity page

You will start calling (redirect user) the octorate identity web page

https://{{octorate user backoffice}}/octobook/identity/oauth.xhtml

With the following Query Params (So you should append them to the url encoded):

client_id (mandatory) It's given by Octorate in your welcome mail. The client id identity your application in the world, so it's not a secret and practically means "Hi! I'm Api User X".
redirect_uri (mandatory) Consider that after the user agrees in our web session to give you the permission, we will redirect him to a page you have choosen.
This page should be whitelisted before. As long as you're in developing mode, you can set it up from your api configuration.
After we expect you to contact us to change it (in production mode).
You can register many redirect uri, and specify instead in this url which one we should use.
state (Optional) Is something crypt you can use either to verify the call started from you, or to pass some data that you will need after (like an user id). We will give you back this data afterward.

An example of the previous link would be like this:

https://admin.octorate.com/octobook/identity/oauth.xhtml?client_id=aaaaaaaaaaaaaaaaaaaaaaaaaa&redirect_uri=https%3A%2F%2Fwww.mycompany.com%2Foauth_end.html&state=something_crypted

After the user grants the permission we will call your page with ?code={{secretCode}} at the end

Now you can do you server to server calls to retrieve the credentials.

Have you not still set the redirect uri?
We set as default https://localhost. You can change it either requesting us a new one and using API CONFIGURATION endpoint. Do I need to expose a secure link? (starting with https)
Yes, it's mandatory since otherwise the token can be easily stolen with Man in the middle attacks.

2. Exchange the code for real credentials

Check the headers and params type!

Please note that these calls are done using the header "Content-Type: application/x-www-form-urlencoded" and form-params params.

You need to call the endpoint /identity/token to retrieve a valid refresh and access token

This should be done in maximum one minute after we have redirect the user to your site.
This action MUST be done server to server. You call Octorate Identity Repository to retrieve these tokens.

Request:


                            curl --location --request POST
                            'https://{{enviroment}}/rest/{version}/identity/token'
                            \

                            --data-urlencode 'client_secret={{yoursecret}}' \

                            --data-urlencode 'client_id={{clientid}}' \

                            --data-urlencode 'redirect_uri={{https://your_redirect_uri.com}}'
                            \

                            --data-urlencode 'grant_type=code' \

                            --data-urlencode 'code={{code provided}}

Success Response


{
    "access_token":"token",
    "refresh_token":"myrefreshtoken",
    "expireDate": "2020-03-17T17:41:51.178Z"
}

3. Accessing DATA

The response here gives you the refresh_token that can be used to obtain a new token, and the access_token that you will use in your requests with header:

HTTP HEADER: “Authorization”: “Bearer {{access_token}}”

4. Expiration of the token

In order to obtain a new valid token you should call /identity/refresh method

The response will be like this:


                                {
                                "access_token":"token",
                                "expireDate": "2020-03-17T17:41:51.178Z"
                                }

2: Admin Operations Flow (ApiLogin method)

You can simply execute a post with your secret and client id. Please do this always server to server

                                curl --request POST 'https://{{enviroment}}/rest/{version}/identity/apilogin'
                                \
                                --header 'Content-Type: application/x-www-form-urlencoded' \
                                --data-urlencode 'client_id={{yourclient}}' \
                                --data-urlencode 'client_secret={{theSecretKey}}'
                            

You will get a response like this


                            {
                            "access_token":"token",
                            "expireDate": "2020-03-17T17:41:51.178Z"
                            }

You can use this token for creating properties adding this header to your call.
HTTP HEADER: “Authorization”: “Bearer {{access_token}}”