Enterprise · REST-API

Entwickler-API

Lies Stammdaten, Dienstpläne, Zeitbuchungen und Abwesenheiten direkt per HTTP — für Lohnbuchhaltung, BI oder eigene Tools. Authentifizierung über persönliche API-Keys.

OpenAPI-Spezifikation (YAML) API-Key erstellen

Schnellstart

Unter Einstellungen → API-Zugang einen Key erstellen (nur Enterprise/Trial). Der Key wird nur einmal angezeigt.
Key im Authorization: Bearer ssk_…-Header senden.
Erste Anfrage testen: GET /v1/me.

Basis-URL: https://{PROJECT}.supabase.co/functions/v1/api — {PROJECT} ist deine Supabase-Projekt-Referenz (Teil der SUPABASE_URL).

curl -H "Authorization: Bearer ssk_…" \
  "https://{PROJECT}.supabase.co/functions/v1/api/v1/employees?limit=50&offset=0"

Authentifizierung & Scopes

Header Authorization: Bearer ssk_… (alternativ X-API-Key).
Jeder Key ist an einen Mandanten gebunden — Antworten sind automatisch darauf beschränkt.
Scope read für GET, write für POST. Fehlt der Scope → 403.
Setzt aktiven Enterprise-Plan voraus. Nach Downgrade → 403 FEATURE_LOCKED.

Endpunkte

Methode	Pfad	Beschreibung
GET	/v1/me	Kontext des Keys (Mandant, Plan, Scopes)
GET	/v1/employees	Mitarbeiter auflisten
GET	/v1/employees/:id	Einen Mitarbeiter abrufen
POST	/v1/employees	Mitarbeiter anlegen(write)
GET	/v1/objekte	Objekte auflisten
GET	/v1/objekte/:id	Ein Objekt abrufen
GET	/v1/projekte	Projekte auflisten
GET	/v1/kunden	Kunden auflisten
GET	/v1/shifts	Dienstplan-Zuweisungen (from, to, objekt_id)
GET	/v1/time-entries	Zeitbuchungen (from, to, employee_id)
GET	/v1/absences	Abwesenheiten (status, year)

Vollständige Schemas, Parameter und Beispiele in der OpenAPI-Spezifikation (importierbar in Swagger UI, Postman, Insomnia oder Code-Generatoren).

Pagination & inkrementeller Sync

Listen unterstützen limit (1–1000, Default 100) und offset und liefern ein pagination-Objekt mit total. Folgeseiten: offset = offset + limit.

{
  "success": true,
  "data": {
    "employees": [ { "id": "…", "display_name": "Max Mustermann", "updated_at": "…" } ],
    "pagination": { "limit": 50, "offset": 0, "total": 248 }
  }
}

Für Delta-Sync trägt jede Zeile ein updated_at. Mit updated_since bekommst du nur Änderungen seitdem — merke dir den größten Wert und nutze ihn beim nächsten Abruf.

# Nur seit dem letzten Sync geänderte Zeitbuchungen
curl -H "Authorization: Bearer ssk_…" \
  "https://{PROJECT}.supabase.co/functions/v1/api/v1/time-entries?updated_since=2026-06-01T00:00:00Z"

Rate-Limit

60 Anfragen pro Minute und Key. Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Sekunden). Bei Überschreitung → 429 mit Retry-After. Mehrere Keys erhöhen den Gesamtdurchsatz.

Schreiben & Fehlerformat

Mitarbeiter anlegen (erfordert write-Scope; per-seat Abrechnung beachten):

curl -X POST -H "Authorization: Bearer ssk_…" \
  -H "Content-Type: application/json" \
  -d '{"vorname":"Max","nachname":"Mustermann","rolle":"user"}' \
  "https://{PROJECT}.supabase.co/functions/v1/api/v1/employees"

Fehler folgen immer diesem Schema:

{
  "success": false,
  "error": { "code": "FEATURE_LOCKED", "message": "API access requires an active Enterprise plan" }
}