Doku · Entwickler & Agenten

Vidada technisch — API, Auth und Agenten-Anbindung

Vidada ist eine App-first-Zeiterfassung: Die meisten Funktionen laufen im angemeldeten Mandanten-Kontext. Diese Seite dokumentiert das, was heute maschinen- und integrationsseitig wirklich existiert — und sagt klar, was noch in Entwicklung ist. Jeder Endpunkt unten ist gegen src/app/api/* gegengeprüft.

Authentifizierung

Auth-Modell

Alle App-Endpunkte leiten den Aufrufer aus einem verifizierten Supabase-JWT (HTTP-only-Cookie) ab — nie aus dem Request-Body. Mutierende Endpunkte erzwingen zusätzlich einen Same-Origin-Check (CSRF). Für die normalen App-Endpunkte gibt es keinen allgemein verfügbaren API-Schlüssel. Für agentische Integrationen existiert ein separates, pro-Tenant ausgestelltes Agent-Token (Bearer vidada_agent_*) — derzeit im Pilot-/Early-Access-Status, siehe unten.

Rollenmodell

Genau ein System, durchgesetzt per RLS in Postgres:

  1. owner
  2. admin
  3. hr
  4. manager
  5. employee

Schutzschichten

  • · Supabase-JWT-Cookie (verifiziert serverseitig)
  • · Same-Origin-CSRF-Check für POST/Mutationen
  • · Rollenprüfung im Handler (roleAtLeast)
  • · MFA-Gate für Lohn-/Voll-Exporte
  • · Rate-Limits pro IP / Tenant-User

Ohne Anmeldung

Öffentliche Endpunkte

Genau zwei Endpunkte sind ohne Session aufrufbar — beide sind bewusst informationsarm gehalten.

GET/api/health

Status für externe Uptime-Monitore. 200 {ok:true}, sonst 503 {ok:false}; bewusst ohne Versions-, Pool- oder Tabellen-Details.

Auth: Keine (kurzer Shared-Cache bei 200)

GET/llms.txt

Maschinenlesbare Kurzbeschreibung nach llmstxt.org — Einstieg für LLMs/Agenten zu Produkt, Preisen und Rechtlichem.

Auth: Keine

Session-authentifiziert

App-Endpunkte

Diese Route-Handler ergänzen die App (Exporte, Abrechnung, Offline-Sync). Sie setzen ein gültiges Session-Cookie des aktiven Mandanten voraus und prüfen Rolle, MFA und aktiven Abo-Status. Aufruf erfolgt heute aus der Vidada-App selbst, nicht von externen Clients.

GET/api/export/datev

HR+ · MFADATEV-/Lohn-Export eines Monats (CSV, Soll/Ist/Saldo, Zuschlagsspalten).

GET/api/export/lodas

HR+ · MFALODAS-Bewegungsdaten-Export (CSV) für die Lohnabrechnung.

GET/api/export/dsgvo

Selbst: angemeldet · Fremd: HR+ · MFADSGVO-Auskunft (Art. 15/20) als strukturierter Personen-Export. Selbstauskunft (Art. 15) für jeden Angemeldeten; fremde Personen (?user=) nur HR+. MFA-Gate, max. 10/h pro Nutzer.

GET/api/export/tenant

Admin+ · MFAVollständiger Mandanten-Export (Datenportabilität).

POST/api/time/offline-sync

Mitarbeiter+PWA-Offline-Stempelungen nachträglich synchronisieren (ArbZG-Enforcement, Lease je Tenant/User).

GET/api/plugins/weather

Mitarbeiter+Wetter-Plugin (Open-Meteo), Standort aus Geo-Klick oder Tenant-Config.

POST/api/billing/checkout

Admin+Stripe-Checkout für ein Abo (Basis/Plus, monatlich/jährlich).

POST/api/billing/portal

Admin+Stripe-Kundenportal-Session (Zahlungsdaten, Rechnungen).

POST/api/tenants

AngemeldetMandant anlegen (Onboarding Schritt 1); Aufrufer-ID aus JWT, nie aus dem Body.

POST/api/absences/certificate

AngemeldetArbeitsunfähigkeits-Nachweis hochladen/verknüpfen.

POST/api/invitations/accept

AngemeldetMitarbeiter-Einladung annehmen (E-Mail-Verifikation Pflicht).

GET/api/legal/[doc]

AngemeldetAkzeptierte Rechtsdokumente (AGB/AVV) als Download.

Exporte lösen einen Datei-Download im angemeldeten Kontext aus; bei Fehlern bleibt der Nutzer in der App (kein Navigieren auf eine Rohtext-Seite).

Eingehend

Webhooks

Diese Endpunkte werden von externen Diensten an Vidada gesendet und per Signatur/Secret verifiziert. Sie sind nicht zum direkten Aufruf durch Integratoren gedacht.

/api/webhooks/stripe

Abo-/Zahlungsereignisse → Tenant-Status, Sitzplatz-Abgleich.

Auth: Stripe-Signatur (STRIPE_WEBHOOK_SECRET)

/api/webhooks/mailgun

Eingehende/zugestellte E-Mail-Events (EU-Versand über Mailgun EU).

Auth: Mailgun-Signatur

Interne Cron-Endpunkte (/api/cron/*) sind mit CRON_SECRET (Bearer) geschützt und nur für den Scheduler bestimmt.

Konzepte

Pläne, Lizenzen & Feature-Gating

Funktionsumfang hängt am Abo des Mandanten und an der Rolle des Nutzers. Endpunkte prüfen beides serverseitig.

Basis

Kern-Zeiterfassung, Team-Kalender, Urlaubs-Workflow.

Plus

Zusatzfunktionen; Plus-gegatete Endpunkte antworten sonst mit FEATURE_REQUIRES_PLUS.

Lizenzen nach Rolle

Führung & Ausbildung sowie Azubi/Praktikum/Minijob mit eigenen Preisstufen.

Preisdetails auf der Preisseite.

Für Agenten

Agenten-Anbindung & MCP

Agenten entdecken Vidada über die maschinenlesbare llms.txt und steuern Zeiterfassungs-, HR- und Export-Funktionen über einen MCP-Server (Model Context Protocol). Authentifizierung über ein pro-Tenant ausgestelltes Agent-Token; jeder Tool-Aufruf läuft RLS-isoliert, rollen-gegated und revisionssicher auditiert.

  • vidada_health_checkÖffentlichLegacy-MCP-Systemstatus (DB, Crons, Pool). Der Poolwert ist bis zum O04/F12-Vollfix nicht belastbar; nicht mit dem flachen HTTP-Healthcheck gleichsetzen.
  • vidada_list_membersHR+Tenant-Mitglieder paginiert auflisten.
  • vidada_query_balanceManager+Zeitkonto-Saldo, Soll/Ist, Urlaubs-/Kranktage.
  • vidada_book_absenceManager+Abwesenheitsantrag einreichen (Status pending bis Genehmigung).
  • vidada_export_payrollHR+ · PlusDATEV-Lohnexport für einen festgeschriebenen Monat.

Der MCP-Server liegt als Reference-Implementierung im Code (src/mcp/vidada-server.ts) mit lauffähigen Use-Case-Beispielen (Saldo abfragen, Abwesenheit buchen, Lohnexport, Onboarding). Der Token-/Agenten-Zugang ist aktuell im Pilot/Early-Access — die allgemeine Freigabe erfolgt nach Abschluss des Sicherheits-Reviews.

Interesse am Pilot-Zugang für agentische Integrationen? Sprich mit uns

Loslegen statt nur lesen

14 Tage kostenlos, ohne Zahlungsdaten.

Kostenlos testen