Skip to main content

Connect your app with OAuth 2.0

What is this all about?

When you connect your app to apaleo, it can read or modify data, or even trigger entire business flows of a hotel. But before gaining access to any of the resources in the REST API, it must get permission from the hotel. This guide will walk you through the authorization process (described in greater detail by the OAuth 2.0 specification).
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.)

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: Any application that would like access to a hotel's data. A user (usually the hotel's owner or admin) must grant permission before the client can access any data.
  • 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 together, to ensure all works fine.
You will need to retrieve a client id and client secret, which the client uses to identify itself during the authorization process. To get these credentials, just send us an email api@apaleo.com and tell us:
  • Client name - your app's name (used for consent screen)
  • Logo url - The URL to client logo (used on consent screen). The logo should be square, with a maximum size of 250 x 250 pixels.
  • Scopes - List of scopes you need. Check our Swagger where each API endpoint describes which scope is required.
  • Redirect url - The URL in your application where users are sent after authorization. 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.

Connect

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

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 authorization URL:
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
  • 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' \
  -F client_id=YOUR_CLIENT_ID \
  -F client_secret=YOUR_CLIENT_SECRET \
  -F grant_type=authorization_code \
  -F code=YOUR_AUTHORIZATION_CODE \
  -F redirect_uri=https://YOUR_APP/callback
  • client_id - Your application's client id.
  • client_secret - Your application's client secret.
  • grant_type - This must be authorization_code.
  • code - The authorization code received from the initial authorize call.
  • redirect_uri - The URL must match exactly the redirect_uri passed to /authorize.
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_tokendirectly, 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
  • client_id - Your application's Client Id.
  • client_secret - Your application's Client Secret.
  • grant_type - To refresh a token use refresh_token.
  • refresh_token - The Refresh Token to use.
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.

Comments

Popular posts from this blog

Getting Started with apaleo APIs

Have a look You can find all of apaleo's API on api.apaleo.io. We use Swagger to describe it, and to generate our documentation.

Sign up The first step is to sign up for an account. After you finish signup you will be able to login to our apaleo app and start configuring your properties. Also you can use the same credentials to access our API using Swagger. Get access for app We're still new and want to get in touch with you before we grant you access. Contact us at api@apaleo.com, to get your very own client credentials that lets you play with the API in our sandbox.
Use it apaleo APIs are protected using OAuth2 - the de-facto standard for API security. Here's a short guide to get you started:

Step 1: To get access to our APIs, you need to use your client id and secret to obtain an access token. Don't have one? Contact us at api@apaleo.com.

Combine your client id and secret into a string, separated by colon yourClientId:YourClientSecret and encode with Base64. This wi…

Channel Integration Guide

With the channel integration you can subscribe for availability, rates and inventory (ARI), create new bookings and modify existing bookings. 
The BasicsGet your sandbox account and check out this guide to learn how you can connect to the apaleo APIs.
API Client All apaleo APIs are described as swagger documents. That lets you generate API clients directly from the swagger.json files. There is a large community, providing client generators for almost every language. For example, swagger code generator is a good project, which allows generation of API clients for Java, PHP, C#, NodeJS and more. This gets you up to speed very fast and as a bonus you can access API documentation within the auto-generated methods and models.
Sandboxapaleo.io is our – and your – playground to do first steps with the API, up to your final integration. Use it to interactively explore the API or to learn the apaleo concepts by navigating the user interface.

These are the links you need to know