(… how to get the secret key)
To register your application, sign up as developer here: https://signup.bookeo.com/?wizardCode=apidev
When you register your application, you will be asked to provide a name and description for the application. The name of an application cannot be changed after its registration.
Once your registration is successful, you will be shown on screen a “secret key”. This key must be kept strictly secret and not shared with anyone.
The secret key, together with the API key described below, must be included in every API call. For more information on how to include the keys in an API call, see Protocol notes .
(… how to get the API Key)
Once your application is registered, you need to obtain authorization from a Bookeo user to access his account. Only the account owner of a Bookeo account can install / uninstall applications.
To obtain authorization, ask the user to click on an “Authorization URL” link, which is provided by Bookeo after you have registered your application. You can find the Authorization URL for your application in your developer account home page. Please note it is not possible to install your application in your own developer account! The application must be installed in a regular Bookeo account, i.e. one capable of accepting bookings.
Before the link can be used, you need to specify the value of the parameter permissions. The value of this parameter must be a comma-separated list of permissions requested by your application. See below for the possible values.
Note how permissions are associated to an authorization (and so to the resulting api key), and not to the application itself. If your application changes and requires new permissions, it will have to ask again for authorization to users that have installed it.
Once the user grants the requested permission to your application, a new API Key will be generated. This key will either be emailed to you, or will be transmitted to your nominated URL via the callback mechanism (see below).
The following permissions can be requested, and be included in the authorization URL.
customers_rw_own: create new customers, and read and write customers created by your application
customers_rwd_own: create new customers, and read, write and delete customers created by your application
customers_r_all: read any customer
customers_rw_all: create, read and write any customer
customers_rwd_all: create, read, write and delete any customer
bookings_rw_own: create new bookings, and read and write bookings created by your application
bookings_rwd_own: create new bookings, and read, write and cancel bookings created by your application
bookings_r_all: read any booking
bookings_rw_all: create, read and write any booking
bookings_rwd_all: create, read, write and cancel any booking
blocks_rw_own: create new blocks, and read and write blocks created by your application
blocks_rwd_own: create new blocks, and read, write and delete blocks created by your application
blocks_r_all: read any block
blocks_rw_all: create, read and write any block
blocks_rwd_all: create, read, write and delete any block
payments_rw_own: create new payments, and read payments created by your application
payments_r_all: read any payment
payments_rw_all: read any payment, and create new payments
availability_r: query the availability of products/services for booking
subaccounts_rw: permission to get the list of subaccounts in a Bookeo Portal account, and to install the application into subaccounts
Note that any “all” permission implies the corresponding “own” permission.
In other words, the permission bookings_rw_all implies also bookings_rw_own, so you do not need to request the latter.
To request multiple permissions, simply list them separated by commas.
When a user installs your application, by default an email is sent to your developer email address (the one you signed up with), containing information about the business , and the API key.
You will then need to use the API key in your code to access the account data.
If you are developing an application that is going to be used by many people, it is recommended to automate the process. In the application settings page, you can specify an Authorization callback URL.
If a callback URL is set, when a user installs your application Bookeo will redirect his browser to your URL, providing the API key as parameter. Your web server can then process the request and store the API key in a database, etc. No manual handling of emails is involved.
Note that when using callback URLs, your web site will need to add a state parameter to the Authorization URL provided to customers.
The state parameter is designed to ensure that the person to whom you give the authorization link is the same person who actually uses it to grant the authorization.
As recommended practice, your platform should generate a random token and store it in the user’s session with your platform/web service, and pass the same token as the value of the state parameter in the authorization URL. The authorization callback request will include, besides the apiKey, a “state” parameter. Your application can then verify that the value of this parameter is the same as the one stored in the user’s session. If it is not, your application should not store or use the api key received.
Your application should generate a new state token for every authorization request.
Let’s assume you want to write an application that needs to create new bookings, and record new payments. This application is specific to a single customer, so you can easily handle the API key manually.
If the user grants the required permissions, Bookeo will generate a new API key and will send you an email containing the API key, and basic business contact details.
At this stage the authorization is completed, and your application can use the combination of secret key and api key to securely invoke the Bookeo API on behalf of the user.
Let’s assume you want to write a public application that needs to create new bookings, and record new payments. You expect this to be installed by many people, so you want to automate the onboarding process.
At this stage the authorization is completed, and your application can use the combination of secret key and api key to securely invoke the Bookeo API on behalf of the user.
Steps 1 to 5 are required only to register your application for the first time. Steps 6 to 8 describe the authorization process that takes place every time a user wants to install your application into his Bookeo account.
When initially developing a public application, you can omit the callback URL for simplicity, and treat the application as if it was a normal, private application. You can specify a callback URL at a later stage.
To verify that your api key and secret key are valid, simply perform an API invocation by opening this URL in your web browser:
https://api.bookeo.com/v2/settings/apikeyinfo?apiKey=your_api_key&secretKey=your_secret_key
