Time Doctor

Before writing a single API call, confirm your API version. Time Doctor has two active APIs that share similar names but have different base URLs, authentication methods, and endpoint structures: - v1.1: base URL https://webapi.timedoctor.com/v1.1 or https://api2.timedoctor.com/v1.1 — authenticated with an API token from account settings. Simpler but an older API. - v2: base URL https://api2.timedoctor.com/api/1.0 — uses OAuth 2.0 Bearer tokens and is Time Doctor's current, recommended API for new integrations. This tutorial uses v2. Do NOT mix v1.1 URLs with v2 tokens or vice versa — the 401 errors you get look identical to wrong-credential errors and are extremely confusing to debug. To get v2 credentials, you need to register an OAuth application with Time Doctor. Contact Time Doctor support or check their developer documentation at timedoctor.com/integrations for the current process to register an app and receive a client ID and client secret. Some plans require that you contact support directly to enable API access. Also note your company ID — when you log into the Time Doctor web app, your URL includes a numeric company ID (https://2.timedoctor.com/123456). This number is required as a path segment in virtually every v2 API endpoint: /api/1.0/{companyId}/worklogs, /api/1.0/{companyId}/users, etc. Missing it returns a 404 that looks misleadingly like a wrong endpoint error.

Time Doctor's OAuth 2.0 authorization-code flow requires a server-side redirect callback to receive the authorization code, and a client secret for the code-to-token exchange. Neither belongs in a Flutter app binary. A Firebase Cloud Function handles both safely. The Cloud Function does three things: (1) provides a redirect endpoint that Time Doctor calls after the user approves access, (2) exchanges the authorization code for access and refresh tokens and stores them in Firestore, and (3) provides a /token endpoint your FlutterFlow app calls to always get a valid, refreshed access token. Create a Node.js Firebase Cloud Function as shown in the code block. Deploy it and use the deployed function URL as the redirect URI when registering your Time Doctor OAuth application. After deploying, trigger the initial authorization by opening the Time Doctor OAuth URL in a browser: https://accounts2.timedoctor.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_FUNCTION_URL&response_type=code&scope=openid email profile After user approval, Time Doctor redirects to your Cloud Function with a code query parameter. The function exchanges the code for tokens and stores them in Firestore. From that point, your FlutterFlow app calls the /timeDoctorToken endpoint whenever it needs a fresh access token. Store the client ID, client secret, and redirect URI in Firebase Functions config (not in the code file): firebase functions:config:set timedoctor.client_id='...' timedoctor.client_secret='...' timedoctor.redirect_uri='...'

1// Firebase Cloud Function — Time Doctor OAuth broker (Node.js, index.js)
2const functions = require('firebase-functions');
3const admin = require('firebase-admin');
4const axios = require('axios');
5admin.initializeApp();
6const db = admin.firestore();
7
8const CLIENT_ID = functions.config().timedoctor.client_id;
9const CLIENT_SECRET = functions.config().timedoctor.client_secret;
10const REDIRECT_URI = functions.config().timedoctor.redirect_uri;
11const TOKEN_URL = 'https://accounts2.timedoctor.com/oauth2/token';
12
13// Step 1: OAuth callback
14exports.timeDoctorOAuth = functions.https.onRequest(async (req, res) => {
15  const code = req.query.code;
16  if (!code) { res.status(400).send('Missing authorization code'); return; }
17
18  try {
19    const tokenRes = await axios.post(TOKEN_URL, new URLSearchParams({
20      grant_type: 'authorization_code',
21      client_id: CLIENT_ID,
22      client_secret: CLIENT_SECRET,
23      redirect_uri: REDIRECT_URI,
24      code
25    }), { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
26
27    const { access_token, refresh_token, expires_in } = tokenRes.data;
28    await db.collection('timeDoctorTokens').doc('default').set({
29      access_token, refresh_token,
30      expires_at: Date.now() + (expires_in * 1000)
31    });
32    res.send('Time Doctor authorization complete. You can close this tab.');
33  } catch (e) {
34    res.status(500).send('Token exchange failed: ' + e.message);
35  }
36});
37
38// Step 2: Token endpoint for FlutterFlow
39exports.timeDoctorToken = functions.https.onRequest(async (req, res) => {
40  res.set('Access-Control-Allow-Origin', '*');
41  if (req.method === 'OPTIONS') {
42    res.set('Access-Control-Allow-Methods', 'GET');
43    res.set('Access-Control-Allow-Headers', 'Content-Type');
44    res.status(204).send('');
45    return;
46  }
47  const doc = await db.collection('timeDoctorTokens').doc('default').get();
48  if (!doc.exists) { res.status(401).json({ error: 'Not authorized yet' }); return; }
49  const { access_token, refresh_token, expires_at } = doc.data();
50
51  if (Date.now() > expires_at - 60000) {
52    const r = await axios.post(TOKEN_URL, new URLSearchParams({
53      grant_type: 'refresh_token',
54      client_id: CLIENT_ID,
55      client_secret: CLIENT_SECRET,
56      refresh_token
57    }), { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
58    await db.collection('timeDoctorTokens').doc('default').update({
59      access_token: r.data.access_token,
60      expires_at: Date.now() + (r.data.expires_in * 1000)
61    });
62    res.json({ token: r.data.access_token });
63  } else {
64    res.json({ token: access_token });
65  }
66});

Open your FlutterFlow project. In the left navigation, click API Calls → + Add → Create API Group. Name it 'Time Doctor'. In the Base URL field, enter: https://api2.timedoctor.com/api/1.0 Do not use the v1.1 URL — https://webapi.timedoctor.com/v1.1 — even if you see it referenced in older tutorials or sibling integrations. Commit to v2 from the start. In the Headers tab, add one header: - Authorization: Bearer {{access_token}} In the Variables tab of the API Group, add: access_token (String type). This group-level variable is populated from App State before any API call runs. Also add a group-level variable for company_id (String type). Since virtually all v2 endpoints have the structure /api/1.0/{companyId}/..., you will need this variable on every call. Adding it at the group level means you configure it once and all API Calls inherit it. To initialize the app: create a separate lightweight API Group pointing to your Firebase Cloud Functions URL. Add a single GET call 'Fetch Token' that calls /timeDoctorToken. Map the JSON path $.token to update the App State variable 'timeDoctorToken'. On app launch, trigger this Fetch Token call first, then set App State 'timeDoctorCompanyId' from the company ID you noted during setup. Every Time Doctor API Call then references both App State variables for the group-level variables.

1// API Group configuration reference:
2// Group name: Time Doctor
3// Base URL: https://api2.timedoctor.com/api/1.0
4// Group-level variables:
5//   access_token (String) — from App State
6//   company_id (String) — from App State
7// Headers:
8//   Authorization: Bearer {{access_token}}
9//
10// Endpoint pattern: /{company_id}/worklogs
11// (company_id is a path segment, not a query param)

Inside the Time Doctor API Group, add your first API Call. Name it 'Get Users'. Endpoint: /{{company_id}}/users (the full URL becomes https://api2.timedoctor.com/api/1.0/COMPANY_ID/users). Method: GET. In the Response & Test tab, paste a sample Time Doctor users response. Create a Data Type 'TimeDoctorUser' with fields: id (String), full_name (String), email (String). Map JSON paths: $.users[*].id, $.users[*].full_name, $.users[*].email. Now add the worklogs call. Name it 'Get Worklogs'. Endpoint: /{{company_id}}/worklogs. Method: GET. Add query parameter variables: - start_date (String) — date in YYYY-MM-DD format - end_date (String) — date in YYYY-MM-DD format - user_ids (String) — optional, comma-separated user IDs to filter - limit (Integer) — pagination page size (e.g. 100) - offset (Integer) — pagination offset Time Doctor worklog responses can be large — a team of 20 people over a week generates thousands of time entries. Always include start_date, end_date, and limit/offset query parameters. Do not call worklogs without a date range, or the API may return months of data that takes seconds to load and approaches daily rate limits. Create a Data Type 'TimeDoctorWorklog' with fields: id (String), user_id (String), task_name (String), project_name (String), start_time (String), end_time (String), duration (Integer — seconds). Map the JSON paths from the response. Test the call in the test panel using yesterday's date as both start and end to get a small, fast response for verification.

1// GET /{company_id}/worklogs query parameters:
2// start_date: 2026-07-01 (YYYY-MM-DD)
3// end_date: 2026-07-07
4// user_ids: optional, e.g. 'abc123,def456'
5// limit: 100 (max per page)
6// offset: 0 (first page)
7//
8// JSON Paths for worklogs response:
9// $.worklogs[*].id            → TimeDoctorWorklog.id (String)
10// $.worklogs[*].user_id       → TimeDoctorWorklog.user_id (String)
11// $.worklogs[*].task_name     → TimeDoctorWorklog.task_name (String)
12// $.worklogs[*].project_name  → TimeDoctorWorklog.project_name (String)
13// $.worklogs[*].start_time    → TimeDoctorWorklog.start_time (String)
14// $.worklogs[*].length        → TimeDoctorWorklog.duration (Integer, seconds)

On your main dashboard screen, add a DateRangePicker widget (or two separate DatePicker widgets for start/end) at the top. Store the selected dates in App State variables (start_date and end_date as Strings in YYYY-MM-DD format). Add a Button labeled 'Load Worklogs'. When the button is tapped, trigger the Action Flow: first call Get Worklogs with the current App State dates, company_id, and access_token. Store the response as a List of TimeDoctorWorklog in App State. Then call Get Users if you have not already and store as a List of TimeDoctorUser in App State. For the main display, add a ListView widget bound to the users list. For each user row, show the user's full_name and calculate their total duration from the worklogs (you can use a Custom Function in FlutterFlow to filter the worklogs list by user_id and sum the duration integers). Display total hours as formatted text (e.g., '6h 24m'). Add a detail screen that opens when the user taps a team member's row — this screen receives the user_id and full_name as parameters and shows a ListView of that person's individual worklogs for the selected date range, filtered from the App State worklogs list. For the chart view, FlutterFlow's built-in Bar Chart or Line Chart widget can display hours per user or hours per day. Bind the chart data to the aggregated totals you calculate with Custom Functions. Keep polling modest. Do not auto-refresh the worklog data more than once every few minutes. Time Doctor's API has per-day rate quotas that can be exhausted if a dashboard calls the worklogs endpoint on every screen render or with aggressive background polling.

Time Doctor access tokens expire, and the Firebase Cloud Function's /timeDoctorToken endpoint automatically refreshes them before expiry. But your FlutterFlow app needs to handle the case where the cached App State token becomes stale mid-session — for example, if the user keeps the app open for an extended period. In every API Call action in the Action Flow Editor, add a conditional after the call: if the response HTTP status code is 401, trigger the Fetch Token API Call (to your Firebase Cloud Function), update the App State access_token, and retry the original call once. This pattern covers the vast majority of mid-session expiry scenarios. For 404 errors: the most common cause is using the wrong v1.1 base URL or omitting the company ID path segment. If you see 404 on a call that should work, open the API Call's test panel and check the full URL it is constructing — confirm it matches https://api2.timedoctor.com/api/1.0/YOUR_COMPANY_ID/endpoint_name. For rate-limit errors: Time Doctor v2 has per-day quotas on some endpoints. A dashboard that polls worklogs every 30 seconds for a 20-person team can hit these limits within hours. Implement a 'last loaded' App State timestamp and only allow a refresh if more than 5 minutes have passed since the last fetch. Show a 'Data last updated: X minutes ago' label to users so they understand why the refresh button is temporarily disabled. If the OAuth setup feels too complex for your current sprint, RapidDev's team sets up FlutterFlow OAuth integrations like Time Doctor regularly. Book a free scoping call at rapidevelopers.com/contact to discuss options.

1// Action Flow pattern for Time Doctor API calls:
2// 1. Call API: Get Worklogs (with current access_token from App State)
3// 2. Condition: API Response Code == 401
4//    TRUE:
5//      a. Call API: Fetch Token (Firebase /timeDoctorToken)
6//      b. Update App State: timeDoctorToken = $.token
7//      c. Retry: Call API: Get Worklogs
8//    FALSE:
9//      a. Condition: API Response Code == 404
10//         → Show Snack Bar: 'API error — check company ID'
11//      b. Condition: Response Code == 200
12//         → Update App State: worklogs = response list
13//         → Update App State: lastLoaded = current timestamp