How to Integrate Bolt.new with Clockify

Clockify API authentication is straightforward — there is no OAuth dance, no client secret rotation, no token exchange. You get a single API key from your profile and use it as a header on every request. To find your API key: log into app.clockify.me, click your profile avatar in the top-right corner, then click 'Profile Settings'. Scroll to the bottom of the page to the API section. Click 'Generate' if no key exists, or copy your existing key. This key authenticates as you — it has the same permissions as your account. Keep it secret and never expose it in client-side code. Next, you need your workspace ID. Every Clockify account has at least one workspace, and all API calls are scoped to a workspace. The easiest way to get your workspace ID is to look at the URL when you're in the Clockify web app — it appears as a 24-character hex string after /workspaces/. Alternatively, make a GET request to https://api.clockify.me/api/v1/workspaces with your API key header — the response contains your workspace ID and name in JSON. Copy the ID of the workspace you want to use.

1# Test your API key with curl (optional — for verification only)
2# GET https://api.clockify.me/api/v1/workspaces
3# Header: X-Api-Key: your_api_key
4
5# The response will look like:
6# [{"id": "your_workspace_id", "name": "Your Workspace", ...}]

With your API key and workspace ID in hand, configure your Bolt project's environment variables and create a reusable Clockify client. In a Next.js project, server-side environment variables (without the NEXT_PUBLIC_ prefix) are only readable in API routes and server components — this is exactly where Clockify credentials should live. Never access your Clockify API key from a client component or add NEXT_PUBLIC_ to it, as this would expose it in your JavaScript bundle. Creating a shared Clockify client utility in lib/clockify.ts avoids repeating headers in every API route. The client wraps the native fetch API, automatically adding the X-Api-Key header and the base URL. It also handles error responses from Clockify's API — the API returns standard HTTP status codes (401 for bad API key, 403 for missing permissions, 404 for invalid IDs, 429 for rate limit exceeded). Centralizing error handling here keeps your API routes clean. Rate limits: Clockify allows 50 requests per second on free plans and 10 requests per second for enterprise — well above what a dashboard app would need.

1// lib/clockify.ts
2const BASE_URL = 'https://api.clockify.me/api/v1';
3export const WORKSPACE_ID = process.env.CLOCKIFY_WORKSPACE_ID!;
4
5export async function clockifyFetch<T>(
6  path: string,
7  options: RequestInit = {}
8): Promise<T> {
9  const apiKey = process.env.CLOCKIFY_API_KEY;
10  if (!apiKey) throw new Error('CLOCKIFY_API_KEY is not set');
11
12  const response = await fetch(`${BASE_URL}${path}`, {
13    ...options,
14    headers: {
15      'X-Api-Key': apiKey,
16      'Content-Type': 'application/json',
17      ...options.headers,
18    },
19  });
20
21  if (!response.ok) {
22    const text = await response.text();
23    throw new Error(`Clockify API error ${response.status}: ${text}`);
24  }
25
26  return response.json() as Promise<T>;
27}

With the Clockify client ready, build the core API routes your frontend will call. You need at minimum two routes: one to fetch projects (for dropdowns and filtering) and one to fetch time entries for a date range. Clockify's time entries endpoint supports pagination (default 50 entries per page, max 5000) and filtering by date range using ISO 8601 datetime strings with the start and end query parameters. The projects endpoint returns all projects in your workspace including their IDs, names, client associations, color codes, estimated hours, and archived status. Store the project list in your frontend state so you don't need to re-fetch it on every render — projects don't change frequently. For time entries, always filter by date range rather than fetching all entries. A workspace with months of data will return thousands of entries without a date filter, which is slow and wastes API quota. Time entries come back with start/end datetime strings, duration in seconds (as a negative number — this is a Clockify quirk for running timers), project ID, task ID, and description. You'll need to join project IDs with your project list to display project names. The duration field uses ISO 8601 duration format (PT2H30M = 2 hours 30 minutes) for completed entries.

1// app/api/clockify/entries/route.ts
2import { NextResponse } from 'next/server';
3import { clockifyFetch, WORKSPACE_ID } from '@/lib/clockify';
4
5interface ClockifyUser { id: string; email: string; name: string; }
6interface TimeInterval { start: string; end: string | null; duration: string | null; }
7interface ClockifyTimeEntry {
8  id: string;
9  description: string;
10  projectId: string | null;
11  timeInterval: TimeInterval;
12  billable: boolean;
13}
14
15export async function GET(request: Request) {
16  try {
17    const { searchParams } = new URL(request.url);
18    const start = searchParams.get('startDate') || new Date(Date.now() - 7 * 86400000).toISOString();
19    const end = searchParams.get('endDate') || new Date().toISOString();
20
21    const user = await clockifyFetch<ClockifyUser>('/user');
22    const entries = await clockifyFetch<ClockifyTimeEntry[]>(
23      `/workspaces/${WORKSPACE_ID}/user/${user.id}/time-entries?start=${start}&end=${end}&page-size=500`
24    );
25
26    return NextResponse.json(entries);
27  } catch (error: unknown) {
28    const e = error as { message: string };
29    return NextResponse.json({ error: e.message }, { status: 500 });
30  }
31}

With the API routes in place, build a dashboard that aggregates time entries and displays them meaningfully. The most useful view groups time entries by project and calculates total hours per project for a selected date range. This gives a quick answer to 'how much time did we spend on each project this week?' — the most common time tracking question. The aggregation logic runs client-side: fetch all time entries for the date range, group them by projectId, sum up the durations, then join with the project list to get project names. Duration parsing is the trickiest part — Clockify returns ISO 8601 duration strings (PT1H30M15S = 1 hour 30 minutes 15 seconds) for completed entries and null for running timers. Parse these into seconds for arithmetic, then format the totals back into human-readable hours and minutes. Adding a week/month date range picker dramatically improves usability. Use a simple select dropdown for preset ranges (This Week, Last Week, This Month, Last Month) rather than a full date picker to keep the UI simple. The Bolt AI can generate the date calculation logic for each preset. Fetching both projects and entries in parallel with Promise.all reduces the dashboard load time.

1// utils/clockify-duration.ts
2export function parseDuration(isoDuration: string | null): number {
3  if (!isoDuration) return 0;
4  // PT1H30M15S -> seconds
5  const match = isoDuration.match(/PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?/);
6  if (!match) return 0;
7  const hours = parseInt(match[1] || '0');
8  const minutes = parseInt(match[2] || '0');
9  const seconds = parseInt(match[3] || '0');
10  return hours * 3600 + minutes * 60 + seconds;
11}
12
13export function formatDuration(seconds: number): string {
14  const h = Math.floor(seconds / 3600);
15  const m = Math.floor((seconds % 3600) / 60);
16  return `${h}h ${m.toString().padStart(2, '0')}m`;
17}

Creating time entries programmatically lets users log time directly from your app. The Clockify API accepts POST requests to /workspaces/{workspaceId}/time-entries with a JSON body containing the start time, end time (or duration), project ID, task ID (optional), description, and billable flag. All datetime values must be in UTC ISO 8601 format. The entry creation API route is straightforward: validate the required fields, call the Clockify API, and return the created entry. One important validation: if both end and duration are provided, Clockify uses end. If only duration is provided without end, Clockify calculates the end time. Always send start and end for completed entries. For creating a running timer (no end time), omit the end field entirely. Webhooks are the only part of this integration that requires deployment. If you want real-time notifications when team members start or stop timers — for example, to update a live dashboard or trigger notifications — Clockify needs to send HTTP POST requests to your app. Since Bolt's WebContainer has no public URL, webhooks cannot reach it during development. Deploy to Netlify or Bolt Cloud, then configure webhooks in Clockify's workspace settings under Integrations → Webhooks, pointing to your deployed /api/clockify/webhook endpoint.

1// app/api/clockify/entries/route.ts — POST handler (add to existing file)
2import { clockifyFetch, WORKSPACE_ID } from '@/lib/clockify';
3import { NextResponse } from 'next/server';
4
5export async function POST(request: Request) {
6  try {
7    const body = await request.json();
8    const { projectId, description, start, end, billable = false } = body;
9
10    if (!start || !end) {
11      return NextResponse.json(
12        { error: 'start and end are required' },
13        { status: 400 }
14      );
15    }
16
17    const entry = await clockifyFetch(
18      `/workspaces/${WORKSPACE_ID}/time-entries`,
19      {
20        method: 'POST',
21        body: JSON.stringify({
22          start,
23          end,
24          description: description || '',
25          projectId: projectId || null,
26          billable,
27        }),
28      }
29    );
30
31    return NextResponse.json(entry, { status: 201 });
32  } catch (error: unknown) {
33    const e = error as { message: string };
34    return NextResponse.json({ error: e.message }, { status: 500 });
35  }
36}