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	POST /auth/login, then send the cookie on every request
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

List endpoints accept limit and offset query parameters and return a pagination object:

{
  "items": ["..."],
  "pagination": { "limit": 50, "offset": 0, "total": 132 }
}

Errors

Errors use a consistent envelope with a machine-readable code:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name must be between 3 and 100 characters"
  }
}

Status	Meaning
400	Validation failure; the message names the offending field
401	Not authenticated (missing/expired session or machine token)
403	Authenticated but not allowed (role or scope insufficient)
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 and send it back in the X-CSRF-Token header. 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.