Brainforge Knowledge

calendar-clockify-sync-setup

4 min read

Calendar Clockify Sync Setup

Version: 1.0
Date: February 28, 2026
Owner: AI Team

1. Purpose

This guide configures the Platform Calendar Clockify Sync tool (/ai-tools/calendar-clockify) so users can:

  • Load Google Calendar events for a week
  • View existing Clockify entries in the same week
  • Sync selected calendar events into Clockify with optional project assignment
  • Use signed-in Google OAuth (provider_token) for per-user calendar reads, with API key fallback

2. Required Environment Variables

Calendar to Clockify uses per-user credentials only: each user saves their Clockify API key and workspace via Connect Clockify in the app. You do not need to set CLOCKIFY_API_KEY or CLOCKIFY_WORKSPACE_ID in deployment env (e.g. Railway) for normal use.

For local development or headless/API testing you can still set (optional):

# Optional fallback for scripts/agents; not required for the UI
# CLOCKIFY_API_KEY=...
# CLOCKIFY_WORKSPACE_ID=...
GOOGLE_CALENDAR_ACCESS_TOKEN=... # optional for OAuth mode in cloud/headless agents

Optional overrides:

CLOCKIFY_API_URL=https://api.clockify.me/api/v1
GOOGLE_CALENDAR_API_KEY=...
GOOGLE_CALENDAR_ID=...
GOOGLE_CALENDAR_API_URL=https://www.googleapis.com/calendar/v3

3. Credentials Source (Environment-first for Cloud Agents)

For Cloud Agents and CI-style runs, use environment variables as the primary source.

# Example (local shell)
export CLOCKIFY_API_KEY=...
export CLOCKIFY_WORKSPACE_ID=...
export GOOGLE_CALENDAR_ACCESS_TOKEN=...

If your team uses 1Password, treat it as a source for populating env vars (not as a runtime dependency for agents). Store values in .env.local or team secrets; never commit real secrets.

4. Calendar Access Notes

  • Preferred mode is signed-in Google OAuth from Supabase session (provider_token).
  • Cloud/headless mode can also use GOOGLE_CALENDAR_ACCESS_TOKEN from env.
  • OAuth mode defaults to primary calendar when no calendar ID is provided.
  • API key mode uses GOOGLE_CALENDAR_API_KEY + GOOGLE_CALENDAR_ID.
  • The UI supports overriding calendar ID at runtime.

Supabase Google login should request:

  • https://www.googleapis.com/auth/calendar.readonly

If users previously signed in before this scope was added, they must sign out and sign in again (consent screen) to refresh granted scopes.

If events do not load, verify:

  1. Google Calendar API is enabled for the key
  2. The calendar is accessible to that key
  3. calendarId is correct (format often resembles an email-like ID)

5. Verification

From apps/platform/:

npm run lint
npm run types

Then run the app and open /ai-tools/calendar-clockify to confirm:

  1. Projects load
  2. Week events load
  3. Existing Clockify entries display
  4. Selected events sync into Clockify

6. Troubleshooting

If the Calendar to Clockify page shows these errors, use the checklist below.

MessageCauseFix
PUT /api/brainforge/clockify/credentials 500 or Connect Clockify requires signing in with GoogleIn demo mode (NEXT_PUBLIC_DEV_AUTH_MODE not set or not google), the dev mock user ID is not a valid UUID and cannot be stored in user_clockify_credentials.Set NEXT_PUBLIC_DEV_AUTH_MODE=google in .env.local, then sign in with Google. Connect Clockify requires a real auth user.
Failed to query saved Clockify credentialsThe user_clockify_credentials table is missing or Supabase query failed (e.g. migration not applied, or wrong Supabase project).Run Supabase migrations so 006_create_user_clockify_credentials_table.sql is applied. In Supabase Dashboard → SQL Editor you can run that migration manually if needed.
CLOCKIFY_API_KEY is not configured / Connect Clockify above…App uses per-user credentials only; no server env fallback.Sign in, then use Connect Clockify on the page to save your API key and workspace. Get the key from Clockify Profile → API; get workspace ID from the workspace URL or apps/mcp-servers/clockify-mcp: CLOCKIFY_API_KEY=your_key npm run get-workspace-id.
No Google auth available. Provide bearer auth, GOOGLE_CALENDAR_ACCESS_TOKEN, GOOGLE_REFRESH_TOKEN (with CLIENT_ID/SECRET), or GOOGLE_CALENDAR_API_KEYNo valid Google Calendar auth: no session token, no env fallback.(1) Preferred: Sign in with Google in the platform (login requests calendar.readonly). If you signed in before that scope was added, sign out and sign in again. (2) Fallback: Set one of: GOOGLE_REFRESH_TOKEN + GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET; or GOOGLE_CALENDAR_ACCESS_TOKEN (short-lived); or GOOGLE_CALENDAR_API_KEY + GOOGLE_CALENDAR_ID. See google-calendar-clockify-setup.md for refresh-token steps.

After fixing env and migration, restart the dev server and reload the page. Use Connect Clockify in the UI to save your API key and workspace (optional if you rely on env fallback; the credentials GET still requires the table to exist).

Graph View