clockify_skill

Overview

This skill integrates Clockify via a managed OAuth gateway to track time and manage projects, clients, tasks, tags, and workspaces. It proxies requests to the Clockify API and injects OAuth credentials so you can call Clockify endpoints using a single MATON_API_KEY. Use it to create and update time entries, manage workspace members, and administer projects and clients programmatically.

How this skill works

Requests are sent to the gateway URL prefix https://gateway.maton.ai/clockify/{native-api-path} and the gateway forwards them to api.clockify.me with your authorized Clockify connection. Authentication uses a Maton API key in the Authorization header; OAuth connections are managed at https://ctrl.maton.ai and can be created, listed, inspected, or deleted. If you have multiple Clockify connections, specify one with the Maton-Connection header.

When to use it

• Track billable or non-billable time and create or stop timers
• Create, update, archive, or delete projects and tasks within a workspace
• Manage clients, tags, and workspace users programmatically
• Fetch time-entry reports or list in-progress timers
• Automate time entry creation for team members via the user-specific endpoints

Best practices

• Set MATON_API_KEY as an environment variable and keep it secret
• Use Maton-Connection header when you manage multiple Clockify accounts to target the correct workspace
• Archive projects or tasks before deleting them to avoid errors
• Use ISO 8601 UTC timestamps (e.g., 2026-02-13T09:00:00Z) and ISO 8601 durations for estimates
• Respect rate limits: 50 requests per second per workspace and implement exponential backoff on 429 responses

Example use cases

• Create a time entry for a team meeting with start and end timestamps
• List all projects in a workspace and archive an inactive project before deletion
• Create a client record and attach it to new projects
• Fetch a user’s time entries to generate a weekly report
• Stop a running timer for a user by PATCHing the user time-entries endpoint