Connect your app with OAuth 2.0

 In Miscellaneous

What is this all about?

apaleo connect allows hotels to connect your application with apaleo with a click of a button. For you this means getting a new hotel connected is no work at all. Like, zero. No mapping of client credentials, no paperwork, nothing. To make this magic work, you need to prepare your application once, and implement the OAuth 2.0 authorization flow. This guide explains how.

From a hotel user’s view, it looks like this:

The most important part is getting the consent of the hotelier, that your application can access specific data and processes of his hotel on apaleo. Which ones exactly, is determined by the scopes. But before we dig into the details, let’s clarify some words.

Terminology

Before learning more about the details of the authorization process, make sure that you are familiar with some of the key terms that are used in this guide:

Client Your application.
API apaleo REST API. This is the place where the client can view and modify a hotel’s data.
User A person having a user account for apaleo, typically a hotel owner or admin. This is the person giving permission to a client to access their hotel’s data through the REST API.

Setup

To be able to use the OAuth flow provided by apaleo, you need to prepare a few things. This only needs to be done once, and we will work with you, to ensure everything is okay.

Landing page

The landing page is the page users get to after clicking “connect” in the apaleo store. The technical minimum you need there is letting users log in or register to your application. But. Not all of the users wanting to connect are already customers of yours. Get your marketing people involved, and optimize the page for conversion!

One point that would make us happy is if you would not only explain why your product is great, but also that this is an integration they won’t get anywhere else. Data going both ways? Hotel and room data is magically set up, using apaleo as a source? Loyalty points displayed directly in the apaleo UI? If you also think this is awesomer than other integrations, this is the place to show off.

Once you’re done with the landing page, head over to the apaleo store, and enter its URL as the connect link.

Consent screen

The consent screen will be rendered by apaleo, as part of the flow described below. Request your API credentials (the ones which work for all hotels) and tell us in the comments:

Client name Your applications’s name, used on the consent screen
Scopes List of scopes you need. Check our Swagger documentation where each API endpoint describes which scope is required. Only one of the scopes is required, if multiple are listed. ‘admin’ lets you access and do everything, and cannot be used for apaleo connect.
How
Redirect URL The URL in your application where users are sent after clicking “authorize” in the connect screen. If further setup is required to establish the connection to apaleo, such as mapping of fields or other configuration, it is a good idea to redirect the user there. Ensure the redirect URL can be called, and is using https.

We will review the data to ensure all will work okay, and get back to you within a few days. This is how an example consent screen looks like:

Success page

After the user authorizes your client, you’re all set. Well, almost. The last important step is storing the refresh-token you get back during the flow, and map it to the customer / hotel on your side.

You can also use this as a trigger to initialize the integration. You can do this automatically, fetching all the data you need from apaleo, or manually. Or you can combine both: Get all rate plans, and let the user do the mapping to your rate codes. Get all rooms, and generate a housekeeping schedule from it, which needs further adjustment. The more you can do automatically, the better the Wow! effect.

Do not forget to display a success message, preferably one that directly shows that the integration works. Think about including the hotel name you just fetched from apaleo, or the number of rooms you found.

Connect

Establishing a connection follows a specific flow. Use this, whenever you want to call the API on behalf of a user.

Note: apaleo’s OAuth 2.0 implementation supports the standard authorization code grant type. You should implement the application flow described below to obtain an authorization code and then exchange it for a token. (The implicit grant type is not supported.)

Step 1: Get the user’s authorization

The purpose of this step is to obtain consent from the user to invoke the API to do certain things (specified in ‘scope’) on behalf of him.
To begin the authorization code flow, your app should first send the user to the consent screen:

https://identity.apaleo.com/connect/authorize?
    response_type=code&
    scope=YOUR_SCOPE&
    client_id=YOUR_CLIENT_ID&
    redirect_uri=https://YOUR_APP/callback&
    state=YOUR_RANDOM_VALUE

Testing: Calling the authorize URL will open the consent screen. When you are asked to log in, use the apaleo credentials, not your client ID and secret.

response_type Indicates the kind of credential that apaleo will return (code vs. token). For this flow, the value must be ‘code’.
scope The scopes which you want to request authorization for. These must be separated by a space. For example, to create reservations and get the list of properties use ‘scope=reservations.create properties.read’.
client_id Your application’s client id.
redirect_uri The URL to which apaleo will redirect the browser after authorization has been granted by the user. The authorization code will be included here, in the ‘code’ URL parameter.
state A randomly generated value provided by your application, which is unique for each authorization request. During the OAuth callback phase, your application must check that this value matches the one you provided during authorization. This mechanism is important for the security of your application.

Step 2: Exchange the authorization code for an access token

Now that you have an authorization code, you must exchange it for an access token that can be used to call apaleo API. Using the authorization code (code) from the previous step, you will need to POST to the token URL:

curl -X POST \
  https://identity.apaleo.com/connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_URL_ENCODED_REDIRECT_URI'
client_id Your application’s client id.
client_secret Your application’s client secret.
code The authorization code received from the initial ‘authorize’ call.
encoded redirect_uri The URL must match exactly the ‘redirect_uri’ passed to ‘/authorize’, and be url encoded

The response contains the access_token, refresh_token, id_token, expires_in and token_type values, for example:

{
  "id_token": "eyJhbGc...BkM2RkZ",
  "access_token": "eyJhbGc...91bnRBZ",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "07fabbd...f7b74bc"
}

Note that ‘refresh_token’ will only be present in the response if you included the ‘offline_access’ scope.

Step 3: Call the API

Once the ‘access_token’ has been obtained it can be used to make calls to the API by passing it as a Bearer Token in the ‘Authorization’ header of the HTTP request:

curl -H 'Authorization: Bearer ACCESS_TOKEN' -X GET https://api.apaleo.com/inventory/v1/properties

Using refresh tokens

A refresh token is a special kind of token that contains the information required to obtain a new access token or ID token. Usually, you will need a new access token only after the previous one expires.
The refresh token allows your app to ask apaleo to issue a new ‘access_token’ or ‘id_token’ directly, without having to re-authenticate the user. This will work as long as the refresh token has not been revoked.
Refresh tokens are subject to strict storage requirements to ensure that they are not leaked.

Use a refresh token

To refresh your token, using the ‘refresh_token’ you already got during authorization, make a ‘POST’ request to the ‘/connect/token’ endpoint in the authentication API, using ‘grant_type=refresh_token’.

curl -X POST \
  https://identity.apaleo.com/connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -F client_id=YOUR_CLIENT_ID \
  -F client_secret=YOUR_CLIENT_SECRET \
  -F grant_type=refresh_token \
  -F refresh_token=YOUR_REFRESH_TOKEN

grant_typeTo refresh a token use ‘refresh_token’

client_id Your application’s client id.
client_secret Your application’s client secret.
refresh_token The Refresh Token to use.
redirect_uri The URL must match exactly the ‘redirect_uri’ passed to ‘/authorize’.

The response will include a new ‘access_token’, its type, its lifetime (in seconds), and the ‘id_token’.

{
  "id_token": "eyJ...b9w",
  "access_token": "eyJ...Vsg",
  "expires_in": 3600,
  "token_type": "Bearer"
}

You should only ask for a new token if the ‘access_token’ has expired or you want to refresh the claims contained in the ‘id_token’. It is bad practice to call the endpoint to get a new ‘access_token’ every time you call an API.

Recommended Posts