Introduction

A connection represent the authorization a property has given to your application to access their data. It can only be created by the property itself and can be revoked at any time by them.

Activating connections between partners and vendors works by using a standard OAuth2 flow to request authorization for data access directly from the partner.

The user is guaranteed to have privileges on granting this access by having to authenticate against Booking.com Extranet before confirming the sharing of the data.

Your application can request the data at any time after the property grant without having to re-issue a property-specific token.

Note

There can be cases when the Extranet login account is linked to multiple hotels. It is referred as Group Login.

Using a library

The easiest and quickest way to integrate is to use a OAuth2 library for your programming language or framework. You can find client libraries for your programming language on the OAuth docs page.

To use one of the libraries you usually only have to plug in a few configuration parametesr, they are, usually:

Parameter Description
clientId Your application id
clientSecret Your application secret token
accessTokenUri https://hub-api.booking.com/v1/oauth2/token
authorizationUri https://hub-api.booking.com/v1/oauth2/authorize
redirectUri Your configured redirect url, needs to be identical to the one on suite portal

Manual implementation

You also have the option to manually implement the authentication flow. Here we present all of the steps the user goes through and what needs to be implemented on your side.

Step 1: App requests access

The flow starts by redirecting the user to the url bellow. To make things easier and ensure the user knows its being redirected to a booking suite domain we provide a standardized button to be used as a starting point of the flow.

https://hub-api.booking.com/v1/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&state=CUSTOM_STRING

The button can be inserted in your app by using the following code:

<!-- Connect with BookingSuite -->
<div id="oauth-btn" data-app-id="{{YOUR APP ID HERE}}" data-redirect-uri="{{ YOUR REDIRECT URI HERE}}"></div>
<script type="text/javascript" async="async" src="https://suiteportal.booking.com/js/oauth2-client-v2.0.js"></script>
<script>
  window.addEventListener('load', function(){
    BookingOAuth.render('oauth-btn');
  });
</script>

Parameters:

Parameter Description
client_id The applications ID (how the API identifies the application)
redirect_uri To where the service should redirect the users after an authorization is granted. It MUST match the redirect url configured during initial setup, however you can pass additional query parameter (ex. user=123456) which will be retained. The endpoint URI MUST NOT include a fragment component (#fragment)
response_type This is the authentication type, the only supported mode is code
state (optional) parameter to associate users/prevent CSRF attacks. more info

Step 2: User authorizes application

When the user clicks the link, they must first login to Extranet, to authenticate their identity (unless they are already logged in). Then they will be redirected to Grants Page where they can authorize or deny the application request. In case of Group Login, there will be a list of property ids to select for authorization.

User image

Note

At this point, Only Booking.com Extranet account with admin access can grant scopes.

Step 3: User is redirected back with authorization code

If the user clicks the "Continue" button, the service redirects the users to the applications redirect URI, which was specified during the registration, along with an authorization code and state (if passed in starting request). The redirect would look something like this assuming the url registered was https://example.com/callback:

https://example.com/callback?code=AUTHORIZATION_CODE&state=CUSTOM_STRING

Step 4: Application requests access token

The application requests an access token from the API, by passing the authorization code along with authentication details, including the client secret, to the API token endpoint. Here is an example POST request to Booking's token endpoint:

https://hub-api.booking.com/v1/oauth2/token

Parameters:

Parameter Description
client_id The applications ID (how the API identifies the application)
client_secret Applications secret token
grant_type OAuth grant type, the only supported value is authorization_code
redirect_uri The same url in configuration, used to verify its the right request on a multi configuration environment
code The authorization code given in step 3

Step 5: End of flow

The previous step will return a response containing the hotel id or ids of the properties that granted access. An access token is also returned but should be ignored as is not used at the moment, it is kept in the response to satisfy libraries that break if no value is returned. If you're using a library the values of hotel ids can be fetched on the extra parameters of the access token response.

{
  "access_token": "ACCESS_TOKEN",
  "hotel_ids": [
    "HOTEL_ID1",
    "HOTEL_ID2"
  ],
  "user_id": "LOGGEDIN USER ID"
}

After this step, the Application is authorized to access data for each of the hotels in the response, until the token is revoked either by the app or property.

Using the flow for sign-in

It is possible to login users using this flow. There is no special implementation required. When any Extranet user with already connected Hotel/Property tries to use the flow, we redirect those users direct to the Step 3 where you can use the provided hotel id information to identify the user.

In case of Group Login, if not all the hotel are connected, then users will be redirected to Step 2 with all the connected hotel already selected, as shown in figure under ‘Group Login’ in Step 2.

Note

We currently don't identify users separately on the Booking.com Extranet, meaning if multiple users that has access to same Hotel/Property on the Booking.com Extranet, they will all be logged-in as the same user on the application side.