Documentation

1. INTRODUCTION

1.1 The importance of the security

In today's digital world, where security breaches are all too common, protecting your booking data is a top priority. That's why Hotelbeds group is taking a proactive approach by requiring a new security layer called Mutual TLS (mTLS) for all booking API integrations. This ensures a more secure connection between your systems and our API.

Next will detail the specific operations affected by this mTLS requirement:

• Hotel availability
• CheckRate
• Booking confirmation
• Booking list
• Booking detail
• Booking change
• Booking cancellation
• Booking reconfirmation

Any use of these operations requires the implementation of the mTLS.

Specification details for these operations as available here: https://developer.hotelbeds.com/documentation/hotels/booking-api/api-reference/

1.2 What Mutual TLS (mTLS) is?

Mutual TLS, often abbreviated as mTLS, is a security protocol that enhances communication between applications by ensuring two-way authentication. This means that both the client (typically, your booking system) and our API server verify each other's identities before exchanging data.

Here's a breakdown of how mTLS works:

1. Client initiates connection: Your booking system initiates a connection to our API server.
2. Server presents certificate: The API server sends a digital certificate containing its identity information.
3. Client verifies the server certificate: Your booking system validates the server's certificate to ensure it's communicating with the genuine API.
4. Client presents its certificate: Your booking system presents its own digital certificate containing its unique identity.
5. Server verifies the client’s certificate: The API server validates your booking system's certificate to confirm it's authorized to access the API.
6. Server grants access: Once both parties are authenticated, a secure encrypted channel is established for data transmission.
7. A secure authenticated connection is established between client and server.

By implementing mTLS, we achieve several security benefits:

• Prevents Impersonation: mTLS eliminates the risk of unauthorized parties masquerading as valid booking systems to access our API.
• Protects Sensitive Data: The encrypted communication channel ensures that booking data exchanged between your system and our API is shielded from eavesdropping attempts.
• Granular Access Control: mTLS allows us to control access to specific API functionalities based on the permissions assigned to your booking system's certificate.
  

2. USING mTLS TO ACCESS HOTELBEDS APIs

Hotelbeds APIs leverage mTLS, which requires a secure two-way exchange of TLS certificates between your booking system (client) and the Hotelbeds server. This mTLS process relies on two key components:

• Private Key: This is a critical piece of security information that must be kept confidential. It acts like a digital signature unique to your booking system and is used in conjunction with the public certificate for secure communication.
  Hotelbeds will never request your private key under any circumstances.

• Public Certificate: This is the public counterpart to your private key and serves as your booking system's identity for mTLS communication. You will need to provide this public certificate to Hotelbeds for them to verify your system's authorization when accessing the API.

The way to provide this information is by uploading the certificate with the use of the intranet of developer.hotelbeds.com and associated with the Api Key you would like to use.

Hotelbeds only accepts certificates signed by any of the trusted certificate authorities (CA) listed in the “Mozilla Root CA Program” here:

https://ccadb.my.salesforce-sites.com/mozilla/IncludedCACertificateReport.

The trusted Certificate Authority (CA) will provide both the private key and public certificate.

The mTLS layer utilizes this public certificate to establish a secure encrypted connection.

2.1 Certificate Renewal

How you renew certificates is very dependent of the Certificate Authority (CA) so will be out of the scope of this document but keep in mind that you will require to renew your certificates before they expire as it won’t be possible to connect to mTLS Hotelbeds APIs with an expired certificate.

HBX will automatically send a notification email one month before the expiration date. The email will be sent to the email address associated with the user of the developer portal.

3. Integrate with Hotelbeds mTLS APIs

To connect to Hotelbeds using mTLS the requests should be authenticated requests using your certificate and private key and should be sent to Hotelbeds mTLS endpoints api-mtls.hotelbeds.com.

Production: api-mtls.hotelbeds.com

Test: api-mtls.test.hotelbeds.com

3.1 Example using curl with a CA

Pass your certificate(client.crt), private key(client.key), and root CA certificate(ca.crt) to curl to authenticate your request. Also see how Api-key and X-Signature are still needed.

4. CERTIFICATE MANAGEMENT

To set up mTLS authentication user will be required to upload a valid certificate to the Hotelbeds developer portal (http://developer.hotelbeds.com) and associate it to the desired Api Keys.

After Loging in the developer portal (developer.hotelbeds.com) in the DASHBOARD tab and under MY API KEYS it will be a new MY API CERTIFICATES tab.

This new tab will contain the list of certificates of the user logged in the developer portal and from here it will be possible to upload a new certificate, give it an alias, associate it to Api Keys and delete them from the developer portal.

4.1 Upload Certificate

On the top right side of the MY API CERTIFICATES page it will be a button Add Certificate that will upload the new certificate.

Optionally an Alias can be given to the certificate.

The only accepted certificates will be .crt, .pem and .cer certificates.

4.2 Associate Certificate to Api Keys

After uploading a Certificate a new modal Associate Certificate to Api Keys will open where it will be possible to associate Api Keys to the certificate.

In the Associate Certificate to Api Keys modal will be two columns My API Keys that will list all the Api Keys of the user and Associated API Keys that will list all the API Keys associated with the certificate.

From here the user will be able to Add/Remove an Api Key to the certificate.

Also, on the MY API CERTIFICATES page clicking on a given certificate will open the modal Associate Certificate to Api Keys where it will be possible to associate Api Keys to the certificate.

4.3 Delete Certificate

On the MY API CERTIFICATES page for each certificate it will be a button Delete that will delete the certificate.

4.4 Manage Api Key and Certificate association.

On the MY API KEYS page by clicking on a given Api Key opens Apikey detail modal where it will be displayed the certificates associated with the Api Key.

5. Notifications

The email address associated with your developer portal user account is crucial for staying informed about important updates. This includes notifications regarding the expiration of your certifications. If the email address is incorrect or outdated, you risk missing critical reminders that could lead to lapsed certifications.

6. Developer portal security

Additionally, we would like to provide you with tips for using the Developer portal (https://developer.hotelbeds.com):

• Always use strong passwords: Passwords are still the most common way to access services online, therefore it is paramount that your passwords follow strict security requirements:
  • Passwords cannot contain the user's account name, or parts of the user's full name.
  • Passwords must not be easily guessable using common dictionaries.
  • When you change your password, you should not reuse your last 5 passwords.
  • Passwords must be at least 10 characters in length.
  • Passwords must contain upper case, lower case, special character (like “@”, “!”, “?”, “$” etc.) and numbers.
• Do not reuse passwords across services: You must use a unique password for every service you are accessing. Should your password be leaked passwords from an insecure place, attackers will be able to use this same password to access all services. Alternating your passwords can prevent this risk.
• Consider using a password manager: There are tools that help you to manage passwords for different sites or services, and you only need to remember one password to retrieve them. But remember also to protect your password manager.
• Change your passwords regularly: It is good practice to change your password regularly; every three months is recommended. If you are concerned that your password is at risk of being stolen, change it immediately.
• Do not respond to suspicious requests for information: if you are asked to share any account information (such as your password), or if you receive any other requests which don’t seem right, please contact us immediately at apitude@hotelbeds.com.

7. Contact information

If you have any questions, please don't hesitate to reach out to your Technical Account Manager (TAM) directly. Alternatively, you can email us at apitude@hotelbeds.com