TokenTimer API

Everything in the TokenTimer dashboard is available through a REST API. The same API contract is shared by TokenTimer Cloud, Self-hosted, and Enterprise, so scripts written against one deployment work on the others. A small number of surfaces exist on only one deployment (auto-sync, system administration, billing); those endpoints are marked with a Self-hosted / Enterprise only or Cloud only badge in the REST Reference and in Common workflows.

New to the API? Start with Authentication, then Common workflows for copy-paste curl recipes.

Base URLs

Deployment	Base URL
TokenTimer Cloud	https://tokentimer.ch (or your staging host)
Self-hosted / Enterprise	Your backend URL, e.g. https://tokentimer.example.com

The interactive REST Reference "Try it" panel and generated code samples use the same origin as this docs page, so they target whatever host you are browsing (local, staging, or production). For hand-written curl examples elsewhere in these docs, replace the host with your own backend URL.

OpenAPI contract

The API is described by a conformance-tested OpenAPI 3.0 specification. Every page in the REST Reference is generated from it.

• Download openapi.yaml
• Self-hosted deployments can serve an interactive Swagger UI at /api-docs by setting ENABLE_API_DOCS=true (see the Configuration Reference)

Always the latest published version

Unlike the Self-hosted and Enterprise guides, this API reference is not versioned in the docs site; it ships the latest published TokenTimer version. If you are running an older self-hosted or enterprise release and need the exact API contract for that version, check out the matching vX.Y.Z tag in the tokentimer-core repository and read packages/contracts/openapi/openapi.yaml directly.

Authentication at a glance

The API uses two authentication methods depending on the surface. See Authentication for full details.

Method	Used for	How
Session cookie	Dashboard-equivalent operations: tokens, workspaces, alerts, audit	Fetch CSRF credentials, POST /auth/login with the token and cookie, then retain the session cookie; see Authentication
Machine API token (ttx_...)	CertOps executor surface: event and evidence reporting from agents, CI, and scripts	Authorization: Bearer ttx_... header

Conventions

Workspace scoping

Almost every resource belongs to a workspace. Workspace-scoped routes carry the workspace ID in the path (/api/v1/workspaces/:id/...); the legacy token routes accept workspace_id as a query or body parameter.

Pagination

Pagination and response envelopes vary by endpoint. Paginated lists commonly accept limit and offset; for example, GET /api/tokens returns a top-level total and filter facets:

{
  "items": ["..."],
  "total": 132,
  "facets": { "category": [], "section": [] }
}

Errors

Many routes return an error message alongside a machine-readable code, for example:

{
  "error": "Token not found",
  "code": "TOKEN_NOT_FOUND"
}

Use each endpoint's REST Reference for its exact pagination and error shape; some legacy routes omit a code or add validation details.

Status	Meaning
400	Validation failure; the message names the offending field
401	Not authenticated (missing/expired session or machine token)
403	Role or scope insufficient, or CSRF credentials missing/invalid
402	The workspace plan does not include this operation (Cloud only)
404	Resource not found, or the feature is disabled on this deployment
409	Conflict, e.g. duplicate resource or idempotency-key replay mismatch
422	Payload rejected, e.g. private key material sent to a CertOps route
429	Rate limited; retry after the interval in Retry-After

CSRF protection

Browser-based (cookie-authenticated) mutating requests require a CSRF token. Fetch one from GET /api/csrf-token, retain the companion cookie, and send the token back in the X-CSRF-Token header. Login also requires this pair; see the complete session recipe. Machine-token routes are CSRF-exempt.

info

curl scripts that log in with POST /auth/login and reuse the cookie jar also need the CSRF header for POST/PUT/PATCH/DELETE requests when CSRF enforcement is enabled on your deployment.

Rate limits

Write-heavy machine surfaces (CertOps executor events and evidence) are rate limited per token. When you receive 429, back off and retry after the Retry-After interval. Idempotency keys make retries safe; see CertOps automation.