(… how to get the secret key)
To register your application, sign up as developer here: https://signup.bookeo.com/?wizardCode=apidev
Please note a developer account (where you register your application) is separate from a business account (where a business takes bookings). You cannot use the same username for two different accounts, so if you already have a business account, simply sign up using a different email address as your username for the developer account.
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.
Applications can use one of two different authorization methods to invoke the Bookeo API: API key, and OAuth2.
You can choose which method your application will use in the application configuration screen.
The API key authorization method is simpler, but only recommended for applications that are custom developed for a particular Bookeo account.
When you choose this method, 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 their account. Only the account owner of a Bookeo account can install / uninstall applications.
To obtain authorization when using the API Key authorization method, 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 be emailed to you and will also be shown on screen to the owner of the account who authorized the application.
The following permissions can be requested, and be included in the authorization URL (for API key authorization) or OAuth2 scope (for OAuth2 authorization).
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 when using API key authorization, simply list them separated by commas. Example: permissions=bookings_rw_own,payments_rw_own
When using OAuth2 authorization, simply add your required permissions in the scope parameter, where they must be separated by a space character, as per OAuth2 protocol.
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 to access the account.
If you need to use the same application with multiple Bookeo accounts, you do not need to register a new application (and obtain a new secret key) for every account. The same secret key can be used with multiple accounts. Simply send the owners of the other accounts the authorization link so that they can install your application, to receive a new API key for each account.
However if you expect to connect many accounts, you should consider using OAuth2 instead.
Bookeo also supports the standard OAuth2 authorization protocol. This method is recommended for third party applications that want to integrate with the Bookeo API to access data on behalf of their users. If you select OAuth2 authorization method in the application configuration screen, you will be shown all the relevant OAuth2 connection details.
If using API Key authorization method, you can verify that your api key and secret key are valid, and check what permissions were granted. 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
If using OAuth2 authorization method, you can check that your access token is valid by making any API call, ex. https://api.bookeo.com/v2/settings/business (including your access token in the Authorization header, as Bearer type).
