Authorization Flow

Before you can access any data you have to create an Authorization Token. Currently Auth Tokens can only be created by managers of a company and have access to the whole company. In the near future we plan to add the ability for single employees to grant auth tokens to their own data.

Requesting an Authorization Token

The first part is to request an auth token which will than be activated by the user. To do this you create a simple POST request to https://worktrail.net/rest/token/request/ which will return your auth token which you have to keep private and an URL to which you have to redirect your user so he can activate this URL.

In addition you have to provide a list of scopes which define what your app will have access to.

Example

curl -H "X-APPKEY: rfzDMJn6kg" -H "X-SECRETAPIKEY: JRATAvrujWUdnHwcbM3EnkqV4dYRfRMSfNDNFMrmzpS5JfuNFy" -d "accesstype=company&scopes=sync-hub-data,read-employees" https://worktrail.net/rest/token/request/

Response:

{
    "authtoken": "ubbgaBzaEbFDsUDkZkfusAyRygNuv9CLfPFm3Ghg9kJEAA8zZq", 
    "redirecturl": "https://worktrail.net/rest/token/auth/?requestkey=yjgV5KC9truysNGjYtPE", 
    "requestkey": "yjgV5KC9truysNGjYtPE"
}

Don't forget to replace your App Key and Secret API Key (Marked as bold) as well as your scopes.

The response contains:

  • authtoken: which you can later user to make authorized requests against our API
  • redirecturl: which you should redirect the user to in a browser window where he has to authorize the request.
  • requestkey: key which you can use to verify whether the user has confirmed the authorization and the key is active. See below for how to validate/confirm that the user authorized your app.

Scopes

Scopes define what data you are allowed to read from the given company. These are a comma separated list of the one or more of the following values:

  • read-employees: Allows your app to request a list of alle employees (this is one of the most basic rights).
  • sync-hub-data: Allows your app to read/write "hub data". (More on that later). Important here is that each app has it's own "namespace" for hub data. So you will never see hub data from other apps, but just your own. This is to make it very simple to write into it without colliding with other apps.
  • read-tasks: Allows your app to read all tasks and projects of that company.
  • write-tasks: Allows your app to write all tasks and projects of a company.
  • read-workentries: Allows your app to read work entries - The tracked time of all employees of the company.

Validating / Confirming Authorization Token

Once an authtoken was requested you can confirm whether the user has confirmed it or not by sending the request key from the previous request to /rest/token/confirm/:

curl -H "X-APPKEY: <APP KEY>" -H "X-SECRETAPIKEY: <API KEY>" -d "requestkey=<REQUEST KEY>" https://worktrail.net/rest/token/confirm/

Response:

{
    "status": "pending", 
    "scopes": "read-employees"
}

Status can be one of:

  • pending: The auth request was successfully register on the server, but the user has not yet given any authorization.
  • rejected: The user has rejected the authorization request. It will never be activated.
  • active: The user has granted you authorization to the requested scopes.