How to build a customer booking overview

A common use case when building a marketplace is building out a small dashboard for your customers. In this guide we will look at how to build a small dashboard with a booking overview for your customers.

Authenticating customers

Typically your customers won't have a Timekit user, like your resources do. This means that you are responsible for authenticating them before your present any booking data to them. Once they are authenticated you can use Timekit's signed search feature to generate a pseudo API key that can be used to fetch their bookings.

The signed search feature is a way to scope a request with the usual API search feature (?search=...), but in a cryptographically safe way that verifies the customer's identity. This is done by signing part of the search query with a JWT token. You can learn more about signed search in the documentation.

📘

What is JWT?

If you are unfamiliar with JWT, here is a good place to learn more: https://jwt.io/

Usually you will use a library to generate the JWT token, depending on which programming language you are using. When generating a token for a signed request, you need to provide 2 things in the payload: An app slug and the data identifying the user (customer.email or meta.something). It looks like this:

{
  "app_slug": "my-app-6165",
  "customer.email": "[email protected]"
}

This is assuming you are using customer.email to identify your users. You can also add meta data to a booking and use that instead. Example:

{
  "app_slug": "my-app-6165",
  "meta.customer_id": "12345"
}

The payload is signed with your app API key using HMAC SHA-256 encryption. Again, you will normally use a library to do this.

Listing bookings

Normally when listing bookings for particular customer, you would simply add a search query to the request like: GET /v2/bookings?search=customer.email:[email protected]

This, however, requires that you authenticate with your app API key, which is not an option on the frontend. If you build a customer facing part of your application, you can't expose you app API key.

If you have generated a token as described in the previous section, you can use that to authenticate the customer by passing it to the url. It looks like this: GET /v2/bookings?search=customer.email:[email protected]&signed_search={JWT_TOKEN}

This request will be securely scoped for the customer and only return their bookings.

Manage bookings

Now your customers have an overview over all their bookings and the next step would be to allow them to manage their bookings. Typically this means applying different actions to the bookings such as cancelling or rescheduling them.

For a customer to apply an action to a booking, you run in to the same authentication problem as earlier. Action links to the rescue! An action link is a cryptographically safe way to allow a customer to perform one specific action to one specific booking. This is done by signing the the booking ID and action with your app API key.

Next problem: You can't sign an action link from the frontend when using signed search, because you would be exposing your app API key. However Timekit allows you to dynamically include a pre-generated action link for each available action when you list a customers booking. It looks like this:
GET /v2/bookings?search=customer.email:[email protected]&signed_search={JWT_TOKEN}&include=customer_action_links

This will include an action link for each available action for each booking that you can safely expose to your customer.

That is all it takes to build a booking overview using two Timekit features: Signed search and action links.