Prerequisite

You need to sign up and have created you first app through the admin interface.
You also need to get your personal api-key from the admin interface, you find you personal api-key under "Account settings", you need the key with the "Full access to all user data and actions" scope.

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. Not to mention that this impersonating is an uncommon way to interact with an API and can prove difficult to comprehend.

Obtaining the App-Token

Obtaining the App-Token is pretty straight-forward, in that you make a request to the /app endpoint including app_token, you just need to get some details right, specifically some special headers.
The example below uses these example values:

  1. App-slug: back-to-the-future
  2. Your email: doc.brown@timekit.io
  3. Your api-key: nvHfRSlhvsnlg4rS7Wt28Ty47qdgegwSu3YK7hPW

The request will look like this:

curl --request GET \
  --url https://api.timekit.io/v2/app?include=app_token \
  --header 'Content-Type: application/json' \
  --header 'Timekit-App: back-to-the-future' \
  --user doc.brown@timekit.io:nvHfRSlhvsnlg4rS7Wt28Ty47qdgegwSu3YK7hPW 

 This will produce a response like this:

{
  "data":{
    "id": "0c3aa054-dcba-4e9f-9717-ac855fe6bb4f",
    "slug": "back-to-the-future",
    "settings": {
      "name": "Back to the Future",
      "callback": "http://myapp.io/#/googlecallback",
      "from_email": "robert.zemeckis@universalpictures.com",
      "from_name": "Robert",
      "contact_name": "Zemeckis",      
      "contact_email": "robert.zemeckis@universalpictures.com"
    },
    "stripe_plan": null,
    "stripe_purchased_at": false,
    "created_at": "1985-12-04 12:00:00",
    "updated_at": "2016-09-01 21:17:55",
    "app_token": [{
      "id": "4d89ce01-aa33-45e4-bdba-8ab383aa8ea5",
      "type": "server-token",
      "description": "Global app-token",
      "token": "live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7",
      "scopes": ["global"],
      "token_generated_at": "2017-12-22T13:15:57+0330",
      "updated_at": "2017-12-22T13:15:57+0330"
    }]
  }
}

The value

live_api_key_8brBKOq70f03VJZwEwU7bvizVdOGORGx

Is the api-key that you will use when authenticating with App-Token.

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!

Did this answer your question?