Brainforge Knowledge

google-calendar-clockify-setup

4 min read

Google Calendar → Clockify Sync Setup

The Calendar Clockify feature (AI Tools > Calendar Clockify) lets users pull upcoming Google Calendar events and sync selected meetings to Clockify time tracking.

Required Environment Variables

VariablePurpose
GOOGLE_REFRESH_TOKENOptional fallback refresh token. Recommended over GOOGLE_CALENDAR_ACCESS_TOKEN because it won’t expire in 1 hour.
GOOGLE_CLIENT_IDRequired if using GOOGLE_REFRESH_TOKEN. Client ID of the Google OAuth app.
GOOGLE_CLIENT_SECRETRequired if using GOOGLE_REFRESH_TOKEN. Client secret of the Google OAuth app.
GOOGLE_CALENDAR_ACCESS_TOKENOptional fallback token if Supabase user session has no Google provider token
CLOCKIFY_API_KEYOptional. No longer required for Calendar to Clockify — each user saves their own key via Connect Clockify in the app.
CLOCKIFY_WORKSPACE_IDOptional. Same as above; per-user credentials are stored in Supabase.

You do not need to set Clockify env in Railway (or any deployment) for Calendar to Clockify. Each user signs in and uses Connect Clockify to save their API key and workspace; the app uses only those per-user credentials. GOOGLE_REFRESH_TOKEN (along with GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET) is highly recommended to fetch long-lived tokens if a signed-in Google session token is unavailable (e.g., when testing in an agent). GOOGLE_CALENDAR_ACCESS_TOKEN is optional and only used as a fallback but will expire quickly.

Add these to apps/platform/.env (or .env.local for local dev). For production, set them in Railway or your deployment environment.

Google Calendar Access Token

The app first uses the signed-in Supabase Google session token (requested with calendar.readonly scope during login). If unavailable (e.g., testing via APIs/agents), the app will use GOOGLE_REFRESH_TOKEN to generate a fresh token automatically. If that fails, it falls back to GOOGLE_CALENDAR_ACCESS_TOKEN. Google OAuth access tokens expire in ~1 hour, so if you rely on the fallback GOOGLE_CALENDAR_ACCESS_TOKEN you need to refresh it regularly:

If you need a reliable token that won’t expire, create an OAuth 2.0 Web application and get a refresh token using the OAuth Playground.

  1. Go to Google Cloud Console.
  2. Create OAuth 2.0 credentials (API type: Web application). Add https://developers.google.com/oauthplayground as an authorized redirect URI.
  3. Save the Client ID and Client Secret in .env as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
  4. Go to Google OAuth 2.0 Playground.
  5. Click the gear icon (⚙️) and check Use your own OAuth credentials. Enter the Client ID and Secret.
  6. In the Playground, select Google Calendar API v3 → https://www.googleapis.com/auth/calendar.readonly.
  7. Click Authorize APIs and sign in.
  8. Click Exchange authorization code for tokens.
  9. Copy the refresh_token value into .env as GOOGLE_REFRESH_TOKEN.
  10. The app will automatically exchange this for a fresh access_token whenever needed.

Option 2: OAuth Playground (quick local testing)

  1. Go to Google OAuth 2.0 Playground.
  2. Click the gear icon (⚙️) and check Use your own OAuth credentials.
  3. Create OAuth 2.0 credentials in Google Cloud Console (API type: Web application).
  4. Add https://developers.google.com/oauthplayground as an authorized redirect URI.
  5. In the Playground, select Google Calendar API v3 → https://www.googleapis.com/auth/calendar.readonly.
  6. Click Authorize APIs and sign in.
  7. Click Exchange authorization code for tokens.
  8. Copy the access_token value into .env as GOOGLE_CALENDAR_ACCESS_TOKEN.

Note: This token expires in ~1 hour. For production, implement refresh tokens or OAuth per user.

Option 2: Service account (production)

For server-side access to a specific user’s calendar:

  1. Create a service account in Google Cloud Console.
  2. Enable domain-wide delegation if using Google Workspace.
  3. Grant the service account access to the target calendar (share the calendar with the service account email).
  4. Use service account credentials to obtain an access token (e.g. via google-auth-library or gcloud auth application-default print-access-token).

Clockify Setup

  1. API key: Clockify Profile Settings → API → Generate API key.
  2. Workspace ID: From your Clockify workspace URL (https://app.clockify.me/workspace/{workspaceId}) or from the Clockify MCP get-workspace-id script: 
    cd apps/mcp-servers/clockify-mcp && CLOCKIFY_API_KEY=your_key npm run get-workspace-id

1Password

Credentials for these integrations can be stored in Brainforge AI Team vault. Use:

op item get "Google Calendar" --vault "Brainforge AI Team"
op item get "Clockify" --vault "Brainforge AI Team"

Where credentials live

  • Local: apps/platform/.env or .env.local (never commit .env)
  • Production: Railway environment variables or your deployment config
  • Reference: apps/platform/.env.example lists optional placeholders

Monthly Clockify rollup (resource planning)

For delivery / allocation docs (e.g. knowledge/delivery/q2-resource-allocation-2026.md), you can pull prior-month hours by person and by Clockify project using the team API key in 1Password:

  • Item: Clockify API Key (vault Brainforge AI Team)
  • Tool: tools/clockify-month-summary/rollup.py — see tools/clockify-month-summary/README.md

This complements HubSpot and Operating: same month’s logged time vs planned allocations and pipeline.

Graph View

Backlinks