Target Audience

The API and this documentation is designed for experienced developers only. It assumes experience in developing web applications using modern technologies such as HTTP, JSON, web services, and so on.

If you are not a web developer, you do not need to read this documentation.

If you’re looking to get a custom application developed for you, and you’re not a developer, we recommend hiring a developer from one of the many marketplaces dedicated to freelance jobs, such as UpWork.

Connection

The address api.bookeo.com resolves to multiple IP addresses spread out across multiple geographical regions (multihoming). This ensures high availability and fault tolerance.

When developing applications that invoke the API, it is important to ensure that if a connection problem arises to the first IP address returned by the DNS service, other addresses are attempted as well. This can often be handled transparently by many modern HTTP client libraries, but it’s worth checking it is the case in your specific circumstances.

It is also recommended to ensure that DNS caching on your server is limited (1 hour or less. We recommend using the recommended TTL, which is 10 minutes), so that your client code has always access to an up-to-date list of available IPs.

Security model

Developers wishing to use the API must follow these two steps:

Register an Application with Bookeo

Obtain authorization from a Bookeo account to access their data. In simple words, the owner of the Bookeo account must “install” the application in his/her account.

By registering an application you are issued with a “secret key“. This key must be kept secret, as it will be used to validate that any API invocation made in the name of your application is effectively made by your application.

Once a user authorizes (installs) your application, you will also be provided with an “api key” that allows your application to access the user’s account data, with a given set of permissions.

Both the “secret key” and the “api key” must be included in any API invocation.

Users can uninstall an application at any time (from the account>Applications page). Once an application is uninstalled, the corresponding api key is no longer valid. Re-installing the same application again will generate a new api key, different from the old one.

Permissions

When your application asks the user for authorization, it must also specify what permissions it needs in order to operate. For example it may require the permission to create new bookings, or to read existing bookings, etc.

The permissions granted by the user are tied to the api key. When Bookeo receives an API invocation, it checks the api key provided to verify that the permissions required to carry out the operation are granted to the key.

It is possible to change permissions requested by your application at any time, by asking the user to go through the same authorization process as for new installations. If the user grants the new permissions, a new api key will be provided, and the old one will no longer be valid.