Timekit developers

Authentication

All authentication is user-based and working with the API is based on the current authenticated user's privileges. We regard users and resources as the same entity, this might be a bit confusing, but regarding authentication, we will stick to the "user" term because it makes the most sense when talking about authentication. Each user only has access to their own calendars, events, meetings etc. with one exception (POST /findtime allows you to search across multiple users/resources)

Basic Authentication

For simple email/password authentication, we use Basic Authentication over HTTPS. Auth is stateless and is sent as Base64 encoded header with each HTTP request.

Each user has a password which is used to retrieve an API token that should go with every subsequent request. The API token is returned when you create the user using POST /resources - remember to save the token on your end!

Making API requests is a matter of supplying the email and API token as authentication headers:

curl
curl \
  -H 'Timekit-App: back-to-the-future' \
  -u doc.brown@timekit.io:nvHfRSlhvsnlg4rS7Wt28Ty47qdgegwSu3YK7hPW \
  https://api.timekit.io/v2/calendars

Google Authentication

In addition to e-mail/password auth, we also support login and sync with Google accounts. The authentication flow is quite different.

Signup and login Users can signup AND login with their Google account using the [GET] /accounts/google/signup endpoint. It will return a Google URL you should redirect the user to. When the user submits their credentials, our API will be pinged with the provided information. If the e-mail isn’t known to Timekit, a new user will be created. If the email is known, the user will be authenticated to Timekit. After a successful signup/login, we’ll redirect the user to your supplied callback with login info (email, api_token etc.) as GET parameters so you can perform authenticated calls after that. Make sure to save the API token for subsequent requests.

Calendar sync The first time a user is created, you should have them pick the calendars they want to sync (or do it for them). This happens on a per calendar basis, through the [PUT] /calendars/:id endpoint.

Once calendars have been toggled, you can initiate a sync with the [GET] /accounts/sync endpoint.

Client-side Authentication

If you're building a frontend application and want to use Timekit API as a backend that users authenticate against directly, you can make them login using email and password to retrieve your a user's API token:

curl
curl -X POST \
   -H 'Timekit-App: back-to-the-future' \
   -d '{
         "email": "doc.brown@timekit.io",
         "password": "FluxCapacitator"
       }' \
   https://api.timekit.io/v2/auth

Which will return:

json
{
    "data": {
        "activated": true,
        "email": "doc.brown@timekit.io",
        "first_name": "Dr. Emmett",
        "img": "http://www.gravatar.com/avatar/7a613e5348d63476276935025",
        "last_name": "Brown",
        "last_sync": null,
        "name": "Dr. Emmett Brown",
        "timezone": "America/Los_Angeles",
        "token_generated_at": null,
        "api_token": "nvHfRSlhvsnlg4rS7Wt28Ty47qdgegwSu3YK7hPW",
    }
}

The email and api_token in the response is what you'll use for subsequent requests to the API as described above.