Migrate to App Token authentication

The API examples on these pages all use the new App-Token authentication and this tutorial will teach you how to use it with the API

d
Written by derrick mak
Updated over a week ago

What is App-Token authentication?

App-Token authentication means that you authenticate as the app which means that you have control over the resources that are part of the particular app. This makes it simpler to request Timekit's API, because the alternative would be that you authenticated as the resource itself and you would then have to store not only the resource's ID but also the resource's credentials in your own database.Not to mention that this impersonation is an uncommon way to interact with an API and can prove difficult to wrap your head around.

Obtaining the App-Token

Obtaining the App-Token is pretty straight-forward. Once you have created a new account through our admin panel, visit the "API settings" page and look for the "App token".

It will look something like this:

live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7

This is the api-key that you will use when authenticating with the App-Token approach.

Using the App-Token

This example shows a get bookings request, authenticated using App-Token:

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

Notice that opposed to the personal authentication used when obtaining the App-Token, we do not specify the Timekit-App, because this is implicit in the App-Token and we do also not provide an email, but do notice the prefixing colon on the authentication(user) setting!

Differences from the Personal-Token

When you make GET calls through the API, you will retrieve data spanning across all your resources. This is usually preferable, but if you would like to filter based on a specific resource, you can use the search query string like so: `

curl --request GET
     --header 'Content-Type: application/json' \
     --url https://api.timekit.io/v2/bookings?search=resource.id:78a4d873-2a68-41c6-bdd4-c0ca5b35efd3 \
     --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7

The same is true with POST, because as the App-Token is not resource specific, you will have to specify which resource should own the new entity. You do this by setting a POST body parameter, like so (notice the "resource_id" key):

curl --request POST \
  --header 'Content-Type: application/json' \
  --url https://api.timekit.io/v2/bookings \
  --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
  --data '{
  "resource_id": "d187d6e0-d6cb-409a-ae60-45a8fd0ec879",
  "graph": "confirm_decline",
  "start": "1955-11-12T21:30:00-07:00",
  "end": "1955-11-12T22:15:00-07:00",
  "what": "Catch the lightning",
  "where": "Courthouse, Hill Valley, CA 95420, USA",
  "description": "The lightning strikes at 10:04 PM exactly! I need you to be there Doc!",
  "customer": {
    "name": "Marty McFly",
    "email": "marty.mcfly@timekit.io",
    "phone": "(916) 555-4385",
    "voip": "McFly",
    "timezone": "America/Los_Angeles"
  }
}'
Did this answer your question?