“Octorate APIs” are designed to let your application create room/rates and accommodations on Octorate and fill the content for these properties.
Is made up of REST calls, and our API follow resource-oriented URLS, accept query params, and always return JSON encoded response.
It uses standard HTTP verbs on these resource like “POST” / “GET” / “PATCH” / “GET”, and so on to understand what you’re attempting to do with these resources, and replies with usually acknowledged HTTP response code, like 404 for missing resources or 200 for successfully processed content.
Following information are described using RFC 2119 microformats like MUST, MAY, SHALL, SHALL NOT, MUST NOT, so please pay attention to these terms.

First of all ensure that:

• - You've already configured or given to octorate your OAuth redirect url (see OAuth flow)
• - You have the "secret key" (api key) if you're using an api key based authentication and also the "public key" if you're using the oauth flow

You can start with a fake property inside our application: https://api.octorate.com/connect/rest/v1
Then when you are ready to set all in production, let us know, we'll do a short certification process and we'll mark your account as production ready

Our suggested authentication and authorization method is a token as OAuth.

OAuth protocol is defined by the RFC 6749 and it's a common way to obtain authorization to a resource.

Inside our APIs there are two kind of resources that you will be allowed to access
- Api Operations: For instance create a new accommodation or retrieve api configuration details
- Accommodations: And by inheritance rooms, reservations and the other related resources.

For the former, we only ask you to login inside our system. That can be done calling the api "apiLogin". For instance here is an example of the curl that you might need to call.
curl --request POST 'https://{{enviroment}}/octobook/rest/identity/apilogin' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id={{yourclient}}' \ --data-urlencode 'client_secret={{theSecretKey}}' Executing this code you will get in the json response an access_token that can be used for an hour to execute requested that not depends on access to any resource. For instance, try to create an accommodation

For the latter instead. the OAuth authorization step is necessary because you need to access to a new resource where likely you still don't the permission to handle.
In that case, the actors will be the Identity Provider (here Octorate), the client (you), the Resource Server (still Octorate) and the user.

The steps will be these:

1. Since you don't have the permission to access the required resource you bring the user (redirect) in Octorate in https://{{enviroment}}/octobook/identity/oauth.xhtml?client_id={{your_client_id}}&redirect_uri={{https://your_redirect_uri.com}}&state={{something crypt to verify}}
2. The user then will be asked to log in, establish a session inside octorate, and grant on Octorate the grants required on all the accommodations he is able to see.
3. Octorate redirects the user to the redirect uri, giving you in the get params the one shot "code", that can be used to retrieve two special tokens:
   The refresh and the access token.
4. You call Octorate Identity Repository to retrieve these tokens. Request: curl --location --request POST 'https://{{enviroment}}/octobook/rest/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}} Response: { "access_token":"token", "refresh_token":"myrefreshtoken", "expireDate": "2020-03-17T17:41:51.178Z" }
5. The refresh token is given only the first time (so you need to have a code to retrieve the refresh token).
   Store it in your repository with your user or the same resources to be able to retrieve the access token again. Here we are, you can access your resource until the expireDate is over with the access token.
   This is the header you will need to always add to your calls. HTTP HEADER: “Authorization”: “Bearer {{access_token}}”
   
6. Great! You've accessed the resource. If the token expires you can still call the /identity/refresh endpoint to retrieve another access token. The refresh token doesn't expire.

In order to process request we the new API, you should follow the previously mentioned method.
Contact us to get the new credentials, after you can obtain the token for your properties using the Identity->migrateApiKey method.

The most basic entities you will find inside Octorate are the Products and the Accommodations.
A products (in the image in Blue) MAY have children in order to form a Rate or a special configuration.
An accommodation (in the image in Orange) MAY have children in order to create an “access network”.
An access network is a container for many properties where a property is entitled to see all the others. So you may have for instance a “California Rentals” container of “Palo Alto Apartment” and “L.A. Apartment”.

Please consider to do all your API calls according to the property you've choosen.
You can't do all calls on the root account, only these API calls works on root account
GET Reservations, GET Rooms, GET PMS Rooms Only one level is possible for Accommodations. Instead many levels are possible for Products. Here's a more detailed example of how the properties can we configured in octorate

When an accommodation sign in inside Octorate, it will have the possibility to setup different connections to many providers (Like Booking.com, Airbnb, Homeaway but also external services like keyless access,etc..).
Every accommodation MUST have his Portal Connection to be connected to a Portal that means that if you're following a multiaccount configuration, and your trying to link one external id to many different "octorate accommodations" (this configuration is available and could be used to give different level of access to different users), you will have to send the same configurations for each portal.