Integrations

TimeTrack is designed to fit into your stack. Connect with payment processors, auth providers, AI assistants, and your own tools via webhooks or the REST API.

💳 Stripe (Billing)

TimeTrack uses Stripe for subscription billing. The integration supports checkout, customer portal, and webhook-driven subscription management.

Setup

1. Create a Stripe account at stripe.com
2. Create three products in Stripe Dashboard: Monthly, Yearly, Lifetime
3. Copy the price IDs to your .env file
4. Configure webhook endpoint: https://api.timetracker.cargoffer.com/api/v1/billing/webhook
5. Set STRIPE_WEBHOOK_SECRET in your env

Endpoints

• GET /api/v1/billing/plans - List available plans
• POST /api/v1/billing/create-checkout-session - Start subscription checkout
• POST /api/v1/billing/create-portal-session - Open customer portal
• GET /api/v1/billing/subscription - Current subscription status
• POST /api/v1/billing/webhook - Stripe webhook receiver

Test Mode

For development, use Stripe test keys and the Stripe CLI to forward webhooks:

stripe listen --forward-to localhost:8017/api/v1/billing/webhook

🔐 Clerk (Authentication)

TimeTrack uses Clerk for user authentication. Clerk provides social login, MFA, session management, and JWT-based API authentication.

Setup

1. Create a Clerk application at clerk.com
2. Enable authentication methods (email, Google, GitHub, etc.)
3. Copy the publishable key (frontend) and secret key (backend) to your env
4. Configure CLERK_JWKS_URL for JWT verification
5. Set the frontend URL in Clerk's allowed origins

Frontend Integration

The React frontend uses Clerk's React SDK:

import {{ ClerkProvider }} from '@clerk/clerk-react'

function App() {{
  return (
    <ClerkProvider publishableKey={{import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}}>
      {{/* Your app */}}
    </ClerkProvider>
  )
}}

Backend JWT Verification

All authenticated endpoints verify the JWT signature using Clerk's JWKS endpoint. Tokens expire automatically; refresh is handled by the Clerk SDK.

🤖 Model Context Protocol (MCP)

TimeTrack provides a built-in Model Context Protocol server, enabling AI assistants like Claude and ChatGPT to interact with your time tracking data.

What is MCP?

MCP is an open protocol that lets AI assistants call tools and access resources. TimeTrack's MCP server exposes time tracking operations as tools that any MCP-compatible client can invoke.

Endpoint

The MCP server runs on SSE transport:

https://mcp.timetracker.cargoffer.com (SSE on port 8000)

Available Tools

Tool	Description
start_timer	Start a timer for a project/task with optional description
stop_timer	Stop the currently active timer
get_active_timer	Check if there's an active timer
log_hours	Create a manual time entry for past work
list_projects	List all accessible projects
create_project	Create a new project
list_clients	List all clients
create_client	Create a new client
get_report	Generate a time report (today, week, month, custom range)
get_dashboard	Get dashboard summary

Example: Connect Claude Desktop

Add to your claude_desktop_config.json:

{{
  "mcpServers": {{
    "timetrack": {{
      "url": "https://mcp.timetracker.cargoffer.com/sse",
      "transport": "sse",
      "headers": {{
        "Authorization": "Bearer YOUR_CLERK_JWT"
      }}
    }}
  }}
}}

Example Conversation

Once connected, you can ask your AI assistant:

• "Start a timer for the Acme Corp website project"
• "Log 3 hours on the Mobile App Redesign task from yesterday"
• "What did I work on this week?"
• "How much time did I spend on the Bug Fixes project this month?"
• "Create a new project called 'Q4 Marketing Campaign' for Acme Corp"

🔌 REST API (Custom Integrations)

For any custom integration, use the REST API directly. See the complete API reference for all 79 endpoints.

Authentication

Two options:

1. Clerk JWT - for user-context requests
2. API Key - for server-to-server automation

Rate Limits

Plan	Req/min	Req/day
Free	60	1,000
Pro	300	50,000
Enterprise	Custom	Custom

SDKs and Client Libraries

You can generate a client SDK from the OpenAPI spec:

# TypeScript / JavaScript
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.timetracker.cargoffer.com/api/openapi.json \
  -g typescript-axios \
  -o ./timetrack-sdk

# Python
openapi-python-client generate \
  --path https://docs.timetracker.cargoffer.com/api/openapi.json \
  --output-path ./timetrack-sdk

# Go
openapi-generator generate \
  -i https://docs.timetracker.cargoffer.com/api/openapi.json \
  -g go \
  -o ./timetrack-sdk

🔔 Webhooks (Coming Soon)

Webhook support for time entry events, project updates, and billing events is on the roadmap. Subscribe to receive notifications when:

• A timer is started or stopped
• A project is created or updated
• A member joins or leaves
• A subscription status changes

📦 Postman / Insomnia

Import the OpenAPI spec directly:

• Postman: File → Import → Link → https://docs.timetracker.cargoffer.com/api/openapi.json
• Insomnia: Import/Export → Import From → URL → https://docs.timetracker.cargoffer.com/api/openapi.json