Latest

Blog Detail Title

Short Content Here

by Author Name

Date Published

Developer

Connect your app with OAuth 2.0

Andrea Stubbe March 2, 2018

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 authorisation flow. This guide explains how.

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

 connect-flow

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 authorisation 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

setup-flowThe 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 optimise 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.

content-scope

Redirect URL The URL in your application where users are sent after clicking "connect" 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:

consent

 

Success page

After the user authorises 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 initialise 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 authorisation code grant type. You should implement the application flow described below to obtain an authorisation code and then exchange it for a token. (The implicit grant type is not supported.)

Step 1: Get the user's authorisation

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 authorisation 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. Don't have a test account to try it out? Get one here.

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 authorisation 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 authorisation has been granted by the user. The authorisation code will be included here, in the 'code' URL parameter.
state A randomly generated value provided by your application, which is unique for each authorisation 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.

During implementation or debugging, you might want to check the contents of those token, for example to read the account code. One handy tool is https://jwt.io/ . They write "[...] We do not record tokens, all validation and debugging is done on the client side", and it should be okay to use them, but - better safe than sorry. We recommend to be cautious, and not post production tokens of real customers there.

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'. Calling the endpoint to get a new 'access_token' every time you call an API works, but we wouldn't call it the best practice.

 

Want more information? You normally don't need this, but if you want to earn bonus points for security, or are a curious person, you can access our open-id configuration on https://identity.apaleo.com/.well-known/openid-configuration.
Andrea Stubbe

Posted by

Andrea Stubbe
Andrea started coding as a kid, paused that for some years trying to find more interesting things, but then ended up doing that for a living. After working as a freelancer, researcher, teacher, and a normal employee in small and giant corporations, she fulfilled her childhood dream and co-founded a company a year ago. Being a fan of microservices since before she knew that term, she’s still contemplating how and if to use them in micro-sized companies.
Comments

RECENT ARTICLES

by Benjamin Schmid

10/10/2019

IBE Integration Guide

Let's talk Internet Booking Engines (IBEs). They work best when directly connected to the PMS, without any intermediaries that might get in the way with delays ...

by Andrea Stubbe

06/13/2019

Digital guest journey with apaleo

apaleo is building software for hotels, and our users are people that work at hotels. To create amazing guest experiences we need you, creators of guest facing ...

by Andrea Stubbe

05/02/2019

Push it! Webhooks in apaleo

The notification service allows you to build or set up apps which subscribe to certain events on apaleo (webhooks). When an event is triggered, we send an HTTP ...

WANT MORE AMAZING THINGS?

Subscribe to our a-list for all the fun:

  • Keep up to date with hotel trends
  • Understand what matters most to hotel clients
  • Sweet gifs and special offers

Get it in your inbox every Monday ;)

By entering your email you expressly consent to receive our newsletter every week and other material related to...