App based auth

Before you can start using our API you must sign up via our admin interface to register a new account (also known as "app" in technical terms).

In the admin interface, navigate to the "API Settings" section where you'll find your App API Key. This is the API Key that you'll use to authenticate with our API when making API requests.

Uses Basic Authentication

We use Basic Authentication over HTTPS. It's simple to use and works across almost every platform and code language available.

Note that basic auth usually requires a email/user-name and a password. But since the API key is tied directly to your app only, we don't need the email as identifier. This means that the username should be omitted (or supplied as an empty string) and the API key is the password.

Server-side integration

Calling our API is straightforward and only requires that the "Authorization" HTTP header is set to your API key. With most HTTP toolkits and SDKs, you don't have to set this manually.

Make a request using cURL

curl --request GET \
  --url https://api.timekit.io/v2/bookings \
  --header 'Content-Type: application/json' \
  --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7

🚧

Notice the prefixing colon!

Authenticating with API-Key does not use the email part of basic authentication, but in order to remain compatible we need to prefix the API-Key with colon, which will tell cURL that the email is an empty string. Do note that this is specific to the cURL implementation!

Make a request using our Javascript SDK

var timekit = require('timekit-sdk');

timekit.configure({
  appKey: 'live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7'
})

timekit.getBookings()
.then(function(response){
  console.log(response);
}).catch(function(response){
  console.log(response);
});

You can find documentation for our JS SDK on Github.

👍

Using the "Try It" functionality in the docs

The "Try It" functionality lets you try each endpoint against Timekits API directly here in the docs! Pretty nifty, eh? We recommend using an api key for an app in test mode!

If you want to make a barebones HTTP call to our API, basic auth works by setting a Authorization header with your base64 encoded key (this tool can help with the encoding). Remember to prefix the key with a colon!

Example:
If your API Key is test_api_key_foobar you must base64 encode it. So go to a site such as https://www.base64encode.org/ and encode :test_api_key_foobar which will result in the value OnRlc3RfYXBpX2tleV9mb29iYXI=. This value is the one you must input for the Authorization header when using "Try It".

Client-side integration

When calling our API from a client-side use-case, we're using a different key that's safe to expose publicly in your frontend. This only grants access to selected endpoints and only exposes a limited set of information. In most cases, this key is only used for out booking widget called booking.js.

In our admin interface, navigate to the "API Settings" and look for the App Widget Key.

Embedding our widget in a webpage is in most cases as easy as copying the embed code found in our admin panel. Just navigate to your project and click the "Share" button - the embed code already includes your App Widget Key.

🚧

Avoid making client-side integrations

The App Widget Key that we provide is primarily used for usage with our booking.js widget.

The main idea to understand the difference between the App API Key and the App Widget Key is that the App API Key has full access to everything in your Timekit account — it is designed to never be revealed to the public. The App Widget Key, however, is designed to give just enough access to public users so that they can find availability and book appointments just for themselves.

If you want to call Timekit from your frontend application, you must be careful to never share the App API Key. So your choice is either to use the App Widget Key (which can be saved in public code), or to relay all API calls through your own backend from where you will call our API. In that way, you have control over access and better insight into requests, responses etc.