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}}”

Case 3: Server to Server API Calls - IP Address Validation

Our API provides functionality to validate whether a given IP address falls within a certain range or matches a specific IP. This document provides information on the format for inputting IP addresses and ranges.

Authentication via IP Address

This authentication method is available as an alternative to Bearer OAuth v2 authentication (granular authentication). This method is recommended for APIs that can guarantee server-to-server calls and can provide proof of strong security practices. It is also suggested for heavy API calls, as we need to whitelist the API user's IP in the firewall to allow for a large volume of API calls.

Steps for Using IP Address Authentication

Follow these steps to use the IP address authentication method:

Use the Admin Login API call as outlined in step 2 of the API documentation. (You will use your secret credential and your client credentials)
This will provide you with a token that is valid for one year.
You can use this token for all admin operations and for operations having /:accommodation in the path.

IP Address Formats

The API accepts IP addresses in two formats:

A single IP address (e.g., "192.168.1.5")
A CIDR block (e.g., "192.168.1.0/24")

Single IP Address

A single IP address consists of four octets (numbers from 0 to 255) separated by periods (dots). Each IP address must be a valid IPv4 address. Here is an example of a single IP address:


                            192.168.1.5

In this case, the API will check if the client's IP address matches this specific IP address.

CIDR Block

A CIDR block consists of an IP address, followed by a slash ("/"), followed by a prefix length. The IP address is in the same format as a single IP address, and the prefix length is a number from 0 to 32. The prefix length specifies how many of the leftmost contiguous bits of the address comprise the network portion. Here is an example of a CIDR block:


                            192.168.1.0/24

In this case, the API will check if the client's IP address falls within the range specified by the CIDR block.

Note

This feature currently only supports IPv4 addresses. If you need to validate IPv6 addresses, additional adjustments will be needed.

As with any feature that involves IP addresses, please be aware of the potential security implications and use this feature responsibly.