How to connect Timeneye data with your stack
🌟 This feature is included in the PREMIUM plan
The public API of Timeneye enables the connection of Timeneye data with other applications in your tech stack that cannot be directly integrated with Timeneye.
A simple guide is provided below for you and your team to explore and understand the API better. Enjoy!
Getting started
The first thing you want to do is go to the Timeneye developers portal. You can also reach it from the side menu in the web application Support -> Developers portal:
To begin, click on the "Create new app" button to generate a new application.
Fill out the Redirect URI and the Name, the other parameters are optional but strongly recommended.
Once created, open it again and add an avatar. This will help the users to recognize your application when giving it permission to get data on their behalf.
Then click "Save" to store the uploaded logo.
Get an authorization token
Timeneye APIs use the OAuth 2.0 with PKCE flow for authentication, so you will have to implement the business logic on your application to let your user authorize the app you just created.
On the API reference page https://app.timeneye.com/api-reference you will find a thorough guide on how to get a token. Follow it to prepare your application to integrate with Timeneye.
Notice: all the API requests are made on behalf of the user who granted authorization to the application. The endpoints authorization is based on the user role, and the retrieved data are only those available to the authenticated user.
For example, members will not be able to create a Client using the POST /clients endpoint or get other members' entries from the GET /entries endpoint.
To access all your account data, you'll need to access using an account admin.
Get the token using Postman
Prerequisites:
-
Make sure that you have the "Allow third-party apps" setting enabled in your Workspace settings
-
Go to the developer portal and change the Redirect URI of your application to "https://oauth.pstmn.io/v1/callback" and click Save.
-
If you don't have the Postman app already, download it from here: https://www.postman.com/downloads/ and install it.
First thing first, download the Timeneye OpenAPI specification file from this link, open Postman, and import the file you just downloaded:
Select "Postman Collection" and click Import.
Open the collection, go to the Authorization tab, and scroll to Configure new token.
Complete the fields as shown below:
-
Token name: a string that identifies the token for later use (e.g. ACME)
-
Grant type: Authorization Code (With PKCE)
-
Callback Url: leave empty and check the Authorize using browser checkbox
-
Auth URL: https://api.timeneye.com/oauth/authorize
-
Client ID: the Client ID that you see in the application list
-
Client Secret: leave empty
-
Code Challenge Method: SHA-256
-
Code Verifier: leave empty
-
State: whatever you like (e.g. ACME)
Scroll to the bottom and click "Create New Access Token", Postman will open a browser tab for you to log in to the Timeneye authorization server. Use your credentials or one of the other available sign-in methods.
You will then be redirected to the authorization page:
When you click on "Grant authorization", you will be redirected to Postman, and a new token will be issued. Click on Use Token to use it for the entire collection.
Now you can explore all the endpoints in the collection and test them out 🎉
Using a personal access token
Sometimes, you want to use the APIs for personal use, without the hassle of creating an application and giving the users access to their data.
To do so, you can issue a Personal access token from the developers' page:
The personal access tokens expire after one year and can't be refreshed; once issued, keep them safe as you won't be able to access them later.
Exploring the endpoints
On the API reference page, you will also find all the supported endpoints. For example, you can visit https://app.timeneye.com/api-reference#/operations/list-entries to see how the GET /api/v1/entries works. On the right side you can try the endpoint by filling the Token field with a valid Bearer token.
Note: Prepend the string "Bearer " to your token on the API-reference page "Try it" section.
FAQs
Where can I find your API documentation?
Our documentation, including all the requests you can make via the API, is available here: https://app.timeneye.com/api-reference
I'm using the old version of the APIs, what should I do to upgrade?
Unfortunately, the new APIs are not back-compatible with the old ones. If you want to use the new version of the APIs you will have to modify your code to target the new ones.
The old APIs will be supported and available until December 31, 2024.
Are there any limitations to the API usage?
In order to be able to offer a reliable service to all our users and customers we limit how many requests can be performed per user-application couple every 5 minutes.
Every user-application couple has a limited number of requests (in the table below) that can be performed in a given window of time.
The number of requests that can be performed every 5 minutes changes based on which plan has the user's account, at the moment of the request.
|
Plan |
Max Requests per 5 minutes |
|---|---|
|
PRO (Legacy) |
1000 |
|
Premium |
2000 |
|
Enterprise |
3000 |
How do I use the refresh token? Do I need to generate a new one for each request?
Timeneye issues short-lived access tokens (1 day), users will need to refresh their access tokens via the refresh token that was provided to them when the access token was issued. The request is the same as requesting an access token, just provide "refresh_token" as "grant_type" and the given refresh token as "refresh_token" in the POST request. Please take a look at Steps to Request an Access Token for more information.
Is there any endpoint for tags and tag lists?
Coming soon 😉