How to Integrate Clockify with V0

You need two values from Clockify before writing any code: your API key and your Workspace ID. Both are straightforward to find in the Clockify web app. To get your API key, click on your profile picture or initials in the top-right corner of Clockify, then select 'Profile Settings' from the dropdown. Scroll down to find the 'API' section. You will see your API key displayed there — click the 'Copy' button. The key is a long hexadecimal string. This key grants full API access to your Clockify workspace including reading all team members' time entries and reports. To find your Workspace ID, go to your Clockify workspace settings. The simplest way is to look at the URL when you are in the workspace settings: https://clockify.me/workspaces/{workspaceId}/settings. The workspaceId portion of the URL (a 24-character hexadecimal string) is your Workspace ID. Alternatively, once you have your API key, you can make a quick test call to https://api.clockify.me/api/v1/workspaces with your API key in the X-Api-Key header — the response contains an array of your workspaces with their IDs. Clockify's API also uses user IDs for fetching specific users' time entries. If you need to filter by user, note the user ID from the /api/v1/workspaces/{workspaceId}/users endpoint. For workspace-wide reports, you only need the workspace ID. Keep both values secure — your API key in particular should never be committed to code or shared publicly.

Add your Clockify credentials to Vercel's environment variables so your Next.js API route can authenticate with the Clockify API securely. Open your Vercel Dashboard, navigate to your project, click the 'Settings' tab, and select 'Environment Variables' from the left sidebar. Add the following two variables: CLOCKIFY_API_KEY: Set this to your Clockify API key. This is a secret — add it for Production, Preview, and Development environments. Do not add a NEXT_PUBLIC_ prefix, which would expose your key in the browser JavaScript bundle and allow anyone who views your site's source to access your workspace data. CLOCKIFY_WORKSPACE_ID: Set this to your 24-character Workspace ID. This identifies which Clockify workspace to query. While not strictly a secret (it appears in API URLs), keeping it in an environment variable makes it easy to switch workspaces without changing code. Save both variables. Trigger a redeployment of your project by pushing a commit to GitHub or clicking 'Redeploy' in Vercel. The new environment variables will be available in the next deployment. For local development, create a .env.local file in your project root with the same variable names and values. This file is already excluded from Git by the V0-generated .gitignore, so your credentials stay out of your repository.

1# .env.local — local development only, excluded from Git
2CLOCKIFY_API_KEY=your_clockify_api_key_here
3CLOCKIFY_WORKSPACE_ID=your_workspace_id_here

Create Next.js API routes that fetch time data from Clockify. Clockify has two main API surfaces: the basic REST API (individual endpoints for time entries, users, projects) and the Reports API (pre-aggregated summaries). For dashboards, the Reports API is usually more efficient because it aggregates data server-side. The Clockify Reports API base URL is https://reports.api.clockify.me/v1 (different from the main API at https://api.clockify.me/api/v1). Both use the same X-Api-Key header for authentication. The summary report endpoint (POST /workspaces/{workspaceId}/reports/summary) accepts a JSON body with date range (dateRangeStart and dateRangeEnd in ISO 8601 format), groupings (USER, PROJECT, CLIENT, or DATE), and optional filters. It returns pre-aggregated totals — much more efficient than fetching thousands of individual time entries and summing them in your app. For the date range, Clockify uses ISO 8601 datetime strings with timezone information. The start of a week in UTC is straightforward to compute in JavaScript. Pass the user's desired date range from the frontend as query parameters (start and end) and convert them to Clockify's expected format in the API route. The basic time entries endpoint at GET /workspaces/{workspaceId}/user/{userId}/time-entries returns individual entries with full detail including description, start, end, project, and tags. This is useful for detailed weekly views. It supports pagination via page and page-size parameters (max 50 entries per page by default).

1import { NextRequest, NextResponse } from 'next/server';
2
3interface ClockifySummaryGroup {
4  _id: string;
5  duration: number;
6  amounts: { amount: number; currency: string }[];
7  name?: string;
8}
9
10interface ClockifySummaryResponse {
11  groupOne: ClockifySummaryGroup[];
12  totals: { totalTime: number; totalAmount: number }[];
13}
14
15export async function GET(request: NextRequest) {
16  const apiKey = process.env.CLOCKIFY_API_KEY;
17  const workspaceId = process.env.CLOCKIFY_WORKSPACE_ID;
18
19  if (!apiKey || !workspaceId) {
20    return NextResponse.json(
21      { error: 'Clockify configuration missing' },
22      { status: 500 }
23    );
24  }
25
26  const { searchParams } = new URL(request.url);
27
28  // Default to current week
29  const now = new Date();
30  const weekStart = new Date(now);
31  weekStart.setDate(now.getDate() - now.getDay());
32  weekStart.setHours(0, 0, 0, 0);
33
34  const weekEnd = new Date(weekStart);
35  weekEnd.setDate(weekStart.getDate() + 6);
36  weekEnd.setHours(23, 59, 59, 999);
37
38  const start = searchParams.get('start') || weekStart.toISOString();
39  const end = searchParams.get('end') || weekEnd.toISOString();
40  const groupBy = searchParams.get('groupBy') || 'PROJECT';
41
42  const reportPayload = {
43    dateRangeStart: start,
44    dateRangeEnd: end,
45    summaryFilter: {
46      groups: [groupBy],
47    },
48    exportType: 'JSON',
49  };
50
51  try {
52    const response = await fetch(
53      `https://reports.api.clockify.me/v1/workspaces/${workspaceId}/reports/summary`,
54      {
55        method: 'POST',
56        headers: {
57          'X-Api-Key': apiKey,
58          'Content-Type': 'application/json',
59        },
60        body: JSON.stringify(reportPayload),
61        next: { revalidate: 300 }, // Cache for 5 minutes
62      }
63    );
64
65    if (!response.ok) {
66      const error = await response.text();
67      console.error('Clockify Reports API error:', error);
68      return NextResponse.json(
69        { error: `Clockify returned ${response.status}` },
70        { status: response.status }
71      );
72    }
73
74    const data: ClockifySummaryResponse = await response.json();
75
76    const groups = data.groupOne.map((group) => ({
77      name: group.name || group._id,
78      totalSeconds: group.duration,
79      totalHours: Math.round((group.duration / 3600) * 100) / 100,
80      billableAmount:
81        group.amounts?.[0]?.amount ?? 0,
82      currency: group.amounts?.[0]?.currency ?? 'USD',
83    }));
84
85    const totals = data.totals?.[0] ?? { totalTime: 0, totalAmount: 0 };
86
87    return NextResponse.json({
88      groups,
89      totalSeconds: totals.totalTime,
90      totalHours: Math.round((totals.totalTime / 3600) * 100) / 100,
91      dateRange: { start, end },
92    });
93  } catch (error) {
94    console.error('Clockify summary fetch failed:', error);
95    return NextResponse.json(
96      { error: 'Failed to fetch Clockify summary' },
97      { status: 500 }
98    );
99  }
100}

With the Clockify API route returning summary data, prompt V0 to generate the visualization components. Time tracking dashboards typically need clear number formatting (converting seconds to hours and minutes), date range controls for navigating between reporting periods, and visual emphasis on the most important metrics. Before crafting your V0 prompt, test your /api/clockify/summary endpoint and note the exact structure of the response data. This lets you reference real field names in your prompt, which produces more accurate components. For a project summary table, describe the columns you want (Project Name, Total Hours, Billable Hours, Billable Amount), any formatting rules (hours displayed as h:mm, amounts formatted as currency), and how you want totals shown. For a chart, describe the chart type (bar chart for comparison, pie chart for proportion) and what each segment or bar represents. Ask V0 to add a date range picker so users can switch between 'This Week', 'Last Week', 'This Month', and 'Custom Range'. When the date range changes, the component should refetch /api/clockify/summary with the new start and end parameters. Include a loading indicator that appears during the refetch. For teams with multiple members, consider asking V0 to add a user filter dropdown that fetches team members from /api/clockify/users and allows filtering the report to a specific person. The Clockify API supports filtering reports by userId in the report payload.

After generating your components, deploy your V0 app to Vercel and verify the Clockify integration works end-to-end in the production environment. In V0, click the 'Deploy' or 'Publish' button to create a live Vercel deployment. V0 will push your code to GitHub and trigger a Vercel build. The build takes approximately 30-60 seconds. Once the deployment URL is live, open it in your browser and navigate to your Clockify dashboard page. If the dashboard loads with real data from Clockify, the integration is working. If you see an error message, open the Vercel Dashboard, go to your project's Functions tab, and check the function logs for your /api/clockify/summary route. The logs will show any errors from the Clockify API call including authentication failures, wrong workspace IDs, or malformed request payloads. A common issue on first deployment is that environment variables are not yet set in Vercel, causing the API route to return a 500 'Clockify configuration missing' error. Verify your environment variables are saved correctly by going to Vercel Dashboard → Settings → Environment Variables. After adding or correcting variables, you must redeploy for them to take effect. Test the date range filters by clicking 'This Week', 'This Month', and 'Last Month'. Verify that different date ranges return different hour totals. Also test with an empty date range (a period with no tracked time) to confirm your empty state displays correctly. For teams building more complex reporting with custom date ranges, multi-user breakdowns, and integration with billing systems, RapidDev can help extend this Clockify integration into a full-featured client reporting platform.