Clockify

Access the Clockify API with managed OAuth authentication. Track time, manage projects, clients, tasks, tags, and workspaces.

Quick Start

CODEBLOCK0

Base URL

CODEBLOCK1

Replace {native-api-path} with the actual Clockify API endpoint path. The gateway proxies requests to api.clockify.me and automatically injects your credentials.

Authentication

All requests require the Maton API key in the Authorization header:

CODEBLOCK2

Environment Variable: Set your API key as MATON_API_KEY:

CODEBLOCK3

Getting Your API Key

1. 1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Clockify OAuth connections at https://ctrl.maton.ai.

List Connections

CODEBLOCK4

Create Connection

CODEBLOCK5

Get Connection

CODEBLOCK6

Response:
CODEBLOCK7

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

CODEBLOCK8

Specifying Connection

If you have multiple Clockify connections, specify which one to use with the Maton-Connection header:

CODEBLOCK9

If omitted, the gateway uses the default (oldest) active connection.

API Reference

User Operations

Get Current User

CODEBLOCK10

Response:
CODEBLOCK11

Workspace Operations

List Workspaces

CODEBLOCK12

Get Workspace

CODEBLOCK13

Create Workspace

CODEBLOCK14

List Workspace Users

CODEBLOCK15

Project Operations

List Projects

CODEBLOCK16

Get Project

CODEBLOCK17

Create Project

CODEBLOCK18

Response:
CODEBLOCK19

Update Project

CODEBLOCK20

Delete Project

CODEBLOCK21

Note: You cannot delete active projects. Set archived: true first.

Client Operations

List Clients

CODEBLOCK22

Get Client

CODEBLOCK23

Create Client

CODEBLOCK24

Response:
CODEBLOCK25

Update Client

CODEBLOCK26

Delete Client

CODEBLOCK27

Tag Operations

List Tags

CODEBLOCK28

Get Tag

CODEBLOCK29

Create Tag

CODEBLOCK30

Response:
CODEBLOCK31

Update Tag

CODEBLOCK32

Delete Tag

CODEBLOCK33

Task Operations

List Tasks on Project

CODEBLOCK34

Get Task

CODEBLOCK35

Create Task

CODEBLOCK36

Response:
CODEBLOCK37

Update Task

CODEBLOCK38

Delete Task

CODEBLOCK39

Note: You cannot delete active tasks. Set status: "DONE" first.

Time Entry Operations

Get User's Time Entries

CODEBLOCK40

Response:
CODEBLOCK41

Create Time Entry

CODEBLOCK42

Create Time Entry for Another User

CODEBLOCK43

Get Time Entry

CODEBLOCK44

Update Time Entry

CODEBLOCK45

Delete Time Entry

CODEBLOCK46

Stop Running Timer

CODEBLOCK47

Get In-Progress Time Entries

CODEBLOCK48

Pagination

Clockify uses page-based pagination:

CODEBLOCK49

Query Parameters:

• - page - Page number (1-indexed, default: 1)
• INLINECODE9 - Items per page (default varies by endpoint)

Response includes a Last-Page header indicating if there are more pages.

Code Examples

JavaScript

CODEBLOCK50

Python

CODEBLOCK51

Create Time Entry (Python)

CODEBLOCK52

Notes

• - All IDs are string identifiers
• Timestamps must be in ISO 8601 format with UTC timezone (e.g., 2026-02-13T09:00:00Z)
• Duration format uses ISO 8601 duration (e.g., PT1H for 1 hour, PT30M for 30 minutes)
• Cannot delete active projects or tasks - must archive them first
• Rate limit: 50 requests per second per workspace
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Troubleshooting: API Key Issues

1. 1. Check that the MATON_API_KEY environment variable is set:

CODEBLOCK53

1. 2. Verify the API key is valid by listing connections:

CODEBLOCK54

Troubleshooting: Invalid App Name

1. 1. Ensure your URL path starts with clockify. For example:

• - Correct: INLINECODE19
• Incorrect: INLINECODE20

Resources

• - Clockify API Documentation
• Clockify API Reference
• Maton Community
• Maton Support