Bookeo
  • Home
  • Our Products
    • Appointments
    • Tours & Activities
    • Classes & Courses
  • About Us
  • News
Sign In Free Trial
  • English
Bookeo
Appointments

Bookeo
Classes & Courses

Bookeo
Tours & Activities

Application Setup

  • Overview
  • Application setup
  • Protocol Notes
  • Webhooks
  • Examples
  • API REFERENCE
 

Registering your application

(… 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 .

Obtaining user authorization for your application

(… 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).

List of permissions

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.

Callback (optional)


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.

Example: normal application, without callback


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.

  1. Register your application by signing up at https://signup.bookeo.com/?wizardCode=apidev
  2. Provide name and description for your application. Do not input a callback URL
  3. Save the details
  4. After saving, you will be provided the secret key, and the Authorization URL to use.
  5. Let’s assume the authorization URL shown is: https://signin.bookeo.com/?authappid=XYZ&permissions=…
  6. Fill in the permissions required by your application, to obtain this URL https://signin.bookeo.com/?authappid=XYZ&permissions=bookings_rw_own,payments_rw_own
  7. Ask the user for whom the application is developed to click on that link
  8. Bookeo will ask the user if he wants to grant permissions to your application, showing your email address as trusted source of the application.

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.

Example: application with callback


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.

  1. Register your application by signing up at https://signup.bookeo.com/?wizardCode=apidev
  2. Provide name and description for your application and a callback URL – let’s assume this is https://www.mydomain.com/bookeointegration
  3. Save the details
  4. After saving, you will be provided the secret key, and the Authorization URL to use.
    Let’s assume the authorization URL shown is:
    https://signin.bookeo.com/?authappid=XYZ&permissions=…&state=…
  5. You then prepare a page in your web application, with a “connect to Bookeo” button or similar.
  6. Upon clicking that button, your web application will generate a random state token, and redirect the user’s browser to this URL:
    https://signin.bookeo.com/?authappid=XYZ&permissions=bookings_rw_own,payments_rw_own&state=ABCD1234
  7. Bookeo will ask the user if he wants to grant the permissions to your application, and if so, will redirect his browser to this callback URL:
    https://www.mydomain.com/bookeointegration?success=true&apiKey=AX56789&state=ABCD1234
  8. Your web application will process the request, verify that the parameter “success=true” is present, and the state parameter matches the value stored in the user’s session, and if so, will store the apiKey provided. If the request contains the parameter success=false, it means the user has refused to grant the requested permissions to your application. In this case, the state and apiKey parameters will not be present.

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.

Test Invocation


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

Products
  • Appointment Scheduling Software
  • Classes & Courses Scheduling Software
  • Tours & Activities Scheduling Software
Company
  • About Us
  • News
  • Contact Us
Technical
  • Integrations
  • Distribution Channels
  • Affiliate / Reseller
  • Hosting & Security
  • Developers API
  • Support Centre
Industries
  • Business types
  • Massage
  • Salon
  • Health and Wellness
  • Fitness
  • Yoga
  • Escape rooms
  • Boat Tours
  • Small businesses
  • Service businesses
  • Privacy Policy
  • Terms of Service
  • GDPR
  • English
© Bookeo 2023