Skip to content
TTrackTimer
API documentation

Authentication and API keys

View Markdown

Create a workspace-bound API key and understand scopes, expiration, and request authentication.

Use a personal API key to call https://www.tracktimer.app/api/v1. Every endpoint requires Authorization: Bearer YOUR_API_KEY. Browser session cookies alone do not authenticate these routes, and there is no API-key query parameter.

Create a key

  1. Sign in and select the workspace the integration should access.
  2. Open Settings. Use Verify for sensitive changes if needed: key creation and revocation require passkey verification within the last five minutes.
  3. Under Personal API keys, enter a recognizable name and select Create key.
  4. Copy the key when shown and store it in your integration's secret manager. The plaintext is shown only at creation.

Keys use the tt_ prefix and expire after 365 days. Create a replacement before expiration, update the integration, then revoke the old key in Settings. The current interface does not offer custom expiration or a scope picker.

Examples use $TRACKTIMER_API_KEY as a placeholder for a secret injected into your shell environment. They contain no working credential. Keep keys out of client-side bundles, repositories, screenshots, and request logs.

Workspace and user boundaries

A key is bound to its creating user and the workspace selected at creation. Switching workspaces in the website does not retarget the key. Each request checks the key and current workspace membership. Invalid bindings or missing membership are rejected.

Project discovery returns assigned, unarchived projects. Owners and admins can discover every active client in their workspace, including clients without projects; other members see clients with assigned projects. Time-entry history contains only the key user's entries in the bound workspace, including historical entries.

Scopes

Keys created in Settings receive all five default scopes:

  • clients:read: discover accessible clients.
  • projects:read: discover accessible projects for a client.
  • projects:write: create projects when the key owner is a workspace owner or admin. Existing keys retain their scopes; create a replacement key to enable this permission.
  • timers:read: read the active timer and personal time-entry history.
  • timers:write: start and stop timers.

The server checks the required scope on every request. A verified key missing it receives 403 INSUFFICIENT_SCOPE. The public API does not provide client creation, project editing, time-entry editing, invoicing, or organization financial reports.

Request and response basics

GET requests need no body. Starting a timer takes JSON with Content-Type: application/json. Timer POST endpoints require a nonblank Idempotency-Key of at most 255 characters after trimming. Persist a fresh unique operation identifier before each intended timer mutation; keep it unchanged when retrying that operation.

Successful v1 responses return HTTP 200 (201 for project creation) and JSON directly, with no data envelope. They include an X-Request-Id header. Error bodies carry their own requestId. All seven operations share a per-key limit of 120 requests per 60-second window. See errors and retries.

First request

curl "https://www.tracktimer.app/api/v1/clients" \
  --header "Authorization: Bearer $TRACKTIMER_API_KEY"