Skip to content
KlokkKlokk Docs

Extensions

In-app usage

Section titled “In-app usage”

Extensions are external services that integrate with Klokk through its API & extension system: a scoped, read-only REST API, outbound webhooks, and inbound WebSocket connections. The configuration variables live in API & Extensions above; this section covers the in-app workflow and the first-party extensions.

A super-admin manages integrations under Admin → API & Extensions (/admin/extensions). Each integration bundles an API key (shown once — store it securely), the scopes it may use, and one connection mode:

  • API only — the extension polls the REST API using its key (/api/v1/status, /users, /clock/states, /time/entries, /time/leaves, /shifts/events, /companies); rate-limited to 60/min per IP.
  • Webhooks — Klokk sends outbound HTTP POSTs on clock-in, clock-out and leave events. Events: clock.in, clock.out, leave.approved, leave.rejected, leave.cancelled (an approved absence was cancelled); each needs the scope webhook:<event>. Events about a person go only to endpoints of their company (or spanning all companies), also when a super admin decides. Test reaches the chosen endpoint only.
  • WebSocket — the extension opens a persistent inbound connection at GET /api/v1/extension/connect.

Scopes (e.g. read:users, read:time_entries, read:companies) authorise each key; grant only what an extension needs. The public API is read-only. Setting EXTENSIONS_ENABLED=false removes the admin routes, the WebSocket endpoint and all webhooks (the plain REST API stays available).