Last updated

Authentication and authorisation

To access the Booking.com Data Portability API, you need to include an OAuth token in every request.

Overview

To enable your application(program or a service) to access the user-provided URL, users must authorize the data export. This authorization process involves the following steps:

  1. User Sign-In: Users must sign in to their Booking.com account.
  2. Granting Access: After signing in, users will receive a prompt to ask them to allow your application to access their data.

This section outlines the steps required to integrate your application with the Booking.com Accounts Portal(account.booking.com) using the OAuth 2.0 protocol.

Prerequisites

Your application must be registered with Booking.com to obtain the client_id and client_secret necessary for accessing user data.

Interaction Diagram

Below is a simplified interaction diagram, with each step detailed in the subsequent sections.

Interaction Diagram

  • Your application: initiates the login and consumes the result
  • Booking.com: shows the UI and handles API requests from your application

Steps

The users sign in with Booking.com to authenticate themselves and allow the data export.

  1. Generate a login link

    Sign In Button

    Create a link directing to the Authorization endpoint with the necessary parameters, and at this stage, generate a state(explained below) to ensure it is returned to you after users allow the data export.

  2. Authorize

    Username-Password Screens

    Redirect the user to the Authorization endpoint on the Booking.com Accounts portal.

  3. Users log in using Booking.com Accounts Portal

    The result is either a successful authentication, or a bailout.

  4. Users are prompted to authorize third-party access to their data.

    Username-Password Screens

    Username-Password Screens

    The result is either a successful authentication, or a bailout.

  5. Booking.com Accounts Portal returns an authorization code at the redirect URL.

  6. Your API effectively manages any errors that may occur.

    Users have an option not to allow the data export by using the "Not now" button on the OAuth pop-up. In this case you will receive an error message instead of an authorization code. You follow the instructions for error responses described at the endpoint parameters.

  7. You exchange the code

    You receive a one-time authorization code in the URL parameters. To be able to import user data you need to exchange the code for an access_token. To exchange the code, pass it to the Token endpoint on Booking.com Accounts Portal(parameters).

  8. You get refresh_token and access_token as a result of successful code exchange.

Concepts

Scope

Scopes are permissions required to access a user's data on the Data Portability API. User’s can currently choose between two different scopes:

  1. One-Time Access
    • Scope value: https://account.booking.com/scope/dma
    • Description: Use this scope to import user’s data only once.
  2. Continuous Access
    • Scope value: https://account.booking.com/scope/dma_continuous
    • Description: Use this scope to import user’s data continuously for 180 days. The data updates every 24 hours. If you try to access the user's data before 24 hours have passed, you will receive the same data set as before.

Client Id and Client Secret

The Booking.com Accounts Portal serves as an identity provider. Your application acts as a client that consumes our Data Portability API. To identify and authenticate your client application, we use client_id and client_secret.

If you don't have a client application yet, please start the registration process.

State

Understanding State in Your Application

State is a parameter used to preserve context within your application. When users click 'Log In,' they temporarily leave your application to interact with our portal. After completing this process, they are redirected back to the Authorization Response endpoint in your application. At this point, you may need to answer questions such as:

  • Where should I redirect the user next?
  • What actions did they take on the website before clicking 'Log In'?
  • Which "Log In" button did they click?

The Challenge: When users return to your application, you don't have any information about the previous page/section they were on.

The Solution: To solve this, you need to include the necessary information in the state parameter when redirecting to our portal. Then, you can retrieve and use this information once the user is redirected back to your application.

State Usage:

  1. Your application => Booking.com: Authorization endpoint
  2. Booking.com => Your application: Authorization Response endpoint

Important Notes:

  • The structure of the state is entirely up to your implementation. There are no limitations on the data you can send.
  • However, remember that the state is a public parameter. This means users or attackers can easily modify it, so never include sensitive information.

Redirect URL

The Redirect URL is the URL of the Authorization response endpoint on your application.

The redirect_url is used in two places:

  1. Authorization endpoint
  2. Token endpoint

Redirect URL must be on HTTPS, usage of OAuth2 over HTTP is discouraged to implement as HTTPS is the more secure implementation.

You can have several Redirect URLs configured for your client. For example:

  • https://your-application.com/oauth_callback

Endpoints

Booking.com Accounts Portal Endpoints

These endpoints are on Booking.com Accounts Portal.

Authorization Endpoint

This is the entry point of Accounts Portal, where users are redirected to authenticate themselves.

GET https://account.booking.com/oauth2/authorize HTTP/1.1

GET parameters:

  • response_type: must be set to "code"
  • client_id: your Client Id
  • redirect_url: URL of the Authorization Response endpoint on your application(explanation)
  • state: state provided by your application(explanation), you will get it back in the Authorization Response endpoint
  • scope: scopes requested
  • prompt: supported values: register: show the signup form by default instead of login signin: show the login form even if the user is already logged in signin_only: show the login form and hide account creation none: don’t render any UI; return the error response if the user is not authenticated

Response:

  • successful response: login UI is presented to the user
  • prompt=none: redirect to the Authorization Response endpoint, with code if the user is authenticated or error otherwise
  • error response: will be rendered as JSON, users won't be able to proceed from there

Most common errors:

  • invalid_request, "Malformed redirect_url": redirect URL is not in the proper format

    For example, https/example.

  • invalid_request, "Invalid redirect_uri": redirect URL doesn't belong to the client

    In this case, the redirect URL is valid, however the client doesn't have it whitelisted. Please see Redirect URL for more information.

  • invalid_client: we cannot find this client_id in our database

    Client Id section describes how to create a new client.

  • invalid_scope: scope parameter is not correct

    For example, the scope name is misspelled.
    If everything is correct, most likely the scope doesn't belong to the application. In this case please ask us to enable the scope for your application.

Token Endpoint

This is an endpoint on our portal which is used in backend on your application to obtain an access token by presenting an authorization code or a refresh token.

POST https://account.booking.com/oauth2/token/v2 HTTP/1.1
Authorization: Basic dGVzdDpzZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

HTTP Headers:

  • Authorization: base64-encoded client_id:client_secret

    For example, for client_id="test" and client_secret="secret" it will be Basic dGVzdDpzZWNyZXQ=

POST parameters:

  • grant_type: what's being presented; supported values:
    • authorization_code: exchange a code; code and redirect_url are mandatory
    • refresh_token: exchange a refresh_token; refresh_token is mandatory
  • (when grant_type=authorization_code) code: authorization code obtained on the Authorization Response endpoint on your application
  • (when grant_type=authorization_code) redirect_url: URL of the Authorization Response endpoint on your application(explanation); must be the same as the one sent to the Authorization endpoint
  • (when grant_type=refresh_token) refresh_token: a valid refresh token

Response:

  • successful response: JSON with refresh_token and access_token:

    {
    "expires_in": 600,
    "scope": "https://account.booking.com/scope/dma",
    "refresh_token": "CAESRVJDexcZ-lJHeQkoSyDwjnIkw",
    "access_token": "CAESnAIS0gFSzS2IoVmdBcjb6MQOa9lZjA0qAQQwAQ",
    "token_type": "Bearer"
}

  • error response:

    {
    "error_uri": "https://tools.ietf.org/html/rfc6749#section-2.3",
    "error": "invalid_client",
    "error_description": "OAuth client authentication failed"
}

Most common errors:

  • invalid_client: client id or client secret is not correct

    Client Id section describes how to create a new client.

  • invalid_grant: refresh token or authorization code is incorrect in some way

    For example:

    • authorization code is expired: they expire in 5 minutes;
    • authorization code is not found: check if it's read from url params properly; also make sure the redirect_uri is exactly the same as the one sent to the Authorization endpoint;
    • authorization code is already redeemed: it's possible to make only one request with a code;
    • refresh token doesn't belong to the client: client id must be the same as the one sent to the Authorization endpoint;
    • refresh token is expired: the expiration time varies per client.

  • unsupported_grant_type: value of grant_type is wrong

    It must be either authorization_code, or refresh_token.

  • invalid_scope: scope parameter is not correct

    For example, the scope name is misspelled.
    If everything is correct, most likely the scope doesn't belong to the client. In this case please ask us to enable the scope for your client.

Your Application Endpoints

The following endpoint must be implemented on your application.

Authorization Response Endpoint

This is where users are redirected after leaving our Accounts Portal.

GET https://your-application.com/oauth_result HTTP/1.1

It's not necessary that the endpoint is called oauth_result: the pathname is up to you. You can find more about it in the Redirect URL section.

GET parameters:

  • code: authorization code; the application is supposed to exchange this code using the Token endpoint
  • state: state that can be used for making a decision what to do next(explanation); it's the same state as it was provided in the Authorization endpoint

In case of errors the response doesn't have code parameter. Instead our Accounts Portal will send error parameters:

  • state: same as in the successful response
  • error: possible values:
    • access_denied: user rejected the authentication
  • (optional) error_description: human-readable text providing additional information
  • (optional) error_url: a URL identifying a human-readable web page with information about the error
Previous page
Next page