Skip to main content

How to use the app API

Alex B.
Updated

Introduction

This guide shows developers how to access the bookingtime App API for testing purposes. The bookingtime platform uses the OAuth 2.0 protocol for authentication. This supports common OAuth 2.0 scenarios for single page applications via Authorization Code Flow and machine-to-machine communication via Client Credentials Flow.

If not already created, a Developer Account is needed for authentication.

 

Unauthenticated requests are not allowed.

 

If modules or apps are to be developed for an existing organization, it is currently not possible to directly link them to this organization. To have modules and apps appear in the App Store for organizations, bookingtime must be contacted. In the future it will be possible to connect apps and modules via a separate key.

If apps or modules were developed before an organization was created, they will appear in the App Store. Take a look at the order of steps of our "How to create your first module" article.

 

Please note that the Client Credentials Flow must not be used in single page applications (SPAs) and native applications under any circumstances, unless you are using a testing application that is intended to be deleted later. The client secret must be kept confidential and static client secrets could easily be extracted by third parties!

All necessary information on usage and technical details of our specific implementation can be found in our Authentication Documentation.

 

Overview

Making requests to the bookingtime platform requires that your application is authenticated and authorized to access data. Your application can be authenticated in two ways:

  • App Authentication: bookingtime authorizes your application to access the bookingtime platform.
    Using the Client Credentials Flow.
  • User Authentication: bookingtime, as well as the user, grant your application permission to access and/or modify data.
    Using the Authorization Code Flow.

oauth-intro.png

In both cases, the bookingtime authorization server responds first with an refresh token, which then can be exchanged for an access token:

  {
    "refresh_token": "eyJ0eXAi...",
    "token_type": "Bearer",
    "expires_in": "<time in s>"
  }
  {
    "access_token": "eyJ0eXAi...",
    "token_type": "Bearer",
    "expires_in": "<time in s>"
  }

These tokens are a JSON Web Tokens and their full structure can be seen here. A valid access token allows you to query the bookingtime API:

    curl -H "Authorization: Bearer eyJ0eXAi..."
    https://api.bookingtime.com/app/v3/

At this point, your request should be authenticated, but your app/user may not be permitted to access a specific endpoint.

Your application must be explicitly allowed to access a specific organization and users have various read and write permissions.

You simply want to try out our API or test possible integrations with your system without too much effort?
In this case, we recommend the usage of the Client Credentials Flow. The Client Credentials Flow is used for machine-to-machine authentication and therefore does not need any user interaction.

After creating a new app in the developer service, you will receive a Client ID and Client Secret, which you can use to authenticate your own app. This gives you access to a demo organization and allows you to use all common functions of the bookingtime system. Only user specific endpoints are not allowed. Please note that this is only a recommendation for prototypes to reduce the implementation complexity. The use of the Client Credential Flow may not be allowed for your use case.

Alternatively, you are free to implement the Authorization Code Flow.

 

Request access to the API

Register a developer account at the bookingtime developer service.

 

 

How to use the App API

In this example, we use the client credentials flow to send a successful request to the bookingtime App API using individual credentials. Requests to the bookingtime Module API work analog to this, but the client secret must be omitted or empty.The following credentials are required:

 

 Client ID  Unique ID of your custom app
 Client Secret  Secret to authenticate your app
 Organization ID  Unique token of your demo organization

 

Have your application request authentication

To request a refresh token, an application must make a POST request to the oauth/token endpoint for a client credentials to token bundle exchange.

 

Example Request:

curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=70...YOUR_CLIENT_ID \
    -d client_secret=1234...YOUR_CLIENT_SECRET \
    https://auth.bookingtime.com/oauth/token

Example Response:

  {
    "refresh_token": "eyJ0eX...",
    "token_type": "Bearer",
    "expires_in": 2592000
  }


Exchange refresh token

Exchange the refresh token for an organization specific access token again, send a POST request to the oauth/token endpoint, but this time with the refresh token and the ID of a organization your app is permitted to access.

Example Request:

curl -X POST \
    -d grant_type=refresh_token \
    -d client_id=70...YOUR_CLIENT_ID \
    -d refresh_token=eyJ0eX... \
    -d organization_id=f6...YOUR_ORGANIZATION_ID \
    https://auth.bookingtime.com/oauth/token

Example Response

  {
    "access_token": "eyJ0eX...",
    "token_type": "Bearer",
    "expires_in": 300
  }

Use your access token to query the bookingtime App API

The received access token is valid for 5 minutes and allows you to make requests to the bookingtime App API endpoints that do not require user authorization such as the Show an Organization endpoint.

Example Request:

  curl -X "GET" -H "Authorization: Bearer eyJ0eX...YOUR_ACCESS_TOKEN"
    https://api.bookingtime.com/app/v3/de/organization/f6...YOUR_ORGANIZATION_ID/show

Example Response:

  {
    "class": "ORGANIZATION",
    "id": "f6...YOUR_ORGANIZATION_ID",
    "customId": 123456,
    "timestampAdd": "3219-02-04T08:00:00.000Z",
    "timestampEdit": "3219-02-04T08:00:00.000Z",
    "name": "Demo Organization",
    "rootOrganizationFlag": true,
    "description": {
      "value": "This is an example text for more information about the entity.",
      "inheritance": "OFF",
      "result": "This is an example text for more information about the entity."
    },
  },
  ...

Add your first customer

Now we want to add a new customer named John Doe to your organization. For this we will use the Add Customer endpoint and pass the data in application/json format.

Example Request:

  curl -X "POST" -H "Authorization: Bearer eyJ0eX...YOUR_ACCESS_TOKEN" "Content-Type: application/json"
    -d '{"firstName":"John", "lastName":"Doe"}'
    https://api.bookingtime.com/app/v3/de/organization/f6...YOUR_ORGANIZATION_ID/customer/add

Example Response:

  {
    "class": "CUSTOMER_SHORT",
    "id": "d3...",
    "customId": "",
    "firstName": "John",
    "lastName": "Doe",
    "organizationId": "f6...YOUR_ORGANIZATION_ID"
  },
  ...

 

Related articles

Comments

0 comments

Please sign in to leave a comment.