Authentifizierung

FreeMaint akzeptiert zwei Authentifizierungsmechanismen: JWTs (ausgestellt von /auth/login, verwendet von unseren Web- und mobilen Apps) und API-Schlüssel (erstellt in /company-settings/api, verwendet von Ihren eigenen Integrationen).

JWT (Benutzersitzungen)

1. POST /auth/login — Body: {email, password}. Liefert {access_token, refresh_token}.
2. Authorization-Header senden — Bei jeder Anfrage: Authorization: Bearer <access_token>.
3. Bei Ablauf aktualisieren — POST /auth/refresh mit dem refresh_token, um ein neues access_token zu erhalten. Access-Tokens sind 2 Stunden gültig.

API-Schlüssel (Serverintegrationen)

1. Öffnen Sie /company-settings/api oder /profile/api-keys — Administratoren erstellen Schlüssel unter Firmeneinstellungen > API, ab dem Business-Tarif. Eine Person, deren Rolle die Berechtigung „Persönliche API-Schlüssel erstellen“ hat, erstellt ihre eigenen unter Profil > Sicherheit > API-Schlüssel. Eine Rolle mit der Berechtigung „Integrationen verwalten“ (zum Beispiel die Vorlage Integrationsadministrator) kann die Schlüssel des Unternehmens erstellen, widerrufen und löschen, ohne Administrator zu sein; nur ein Administrator übergibt einen Schlüssel an eine andere Person.
2. Klicken Sie auf „Neuer Schlüssel“. — Legen Sie optional ein Ablaufdatum und eine Zugriffsstufe fest (standardmäßig Nur Lesen). Der Rohschlüssel wird nur EINMAL angezeigt — kopieren Sie ihn sofort.
3. Schlüssel verwenden — Senden Sie bei jeder Anfrage Authorization: Bearer fmk_<rawKey>. Format: beginnt mit fmk_, gefolgt von 32 Hexadezimalzeichen.

Sicherheitshinweise

• API-Schlüssel werden als SHA-256-Hashes gespeichert – sobald Sie den Offenlegungsdialog schließen, ist der Rohwert nicht mehr wiederherstellbar
• Durch das Widerrufen eines Schlüssels wird dieser sofort deaktiviert; Die Zeile wird zur Prüfung aufbewahrt
• Jeder Schlüssel gehört zu genau einem Unternehmen und erreicht nur dessen Daten — ein Datensatz eines anderen Unternehmens wird schlicht nicht gefunden
• Für kurzlebige Integrationen können Schlüssel ein optionales „expiresAt“ haben
• Zugriffsstufen, eine Obergrenze zusätzlich zu den Berechtigungen des Eigentümers: READ (Standard — nur Abfragen), READ_STOCK (Abfragen + adjustStock — ideal für einen reinen Entnahme-Kiosk), FULL (jede Operation, die die Rolle des Eigentümers erlaubt)
• Jeder Schlüssel handelt als sein Eigentümer: Jeder Aufruf trägt dessen Berechtigungen und dessen Datensichtbarkeit, und was er schreibt, wird mit dessen Namen gezeichnet. Wird der Eigentümer deaktiviert, wird der Schlüssel abgelehnt (401, Code API_KEY_OWNER_INACTIVE), bis ein Administrator ihn unter Firmeneinstellungen > API einer anderen Person übergibt — der Schlüsselwert ändert sich nicht.

Eine Integration testen

Es gibt keine separate Sandbox-Umgebung: Ein API-Schlüssel spricht immer die echten Daten des Unternehmens an, zu dem er gehört. Zwei Wege, gefahrlos zu testen. (1) Nutzen Sie ein zweites Unternehmen als Testunternehmen — die Trennung zwischen Unternehmen ist derselbe Mechanismus, der alle Kunden voneinander trennt, sodass nichts, was Sie dort tun, Ihre Produktivdaten erreichen kann. API-Schlüssel erfordern den Business-Tarif, also muss auch dieses Unternehmen im Business-Tarif sein: Ein kostenloses Unternehmen kann keinen Schlüssel erstellen. (2) Für rein lesende Arbeit erstellen Sie einen Schlüssel mit der Zugriffsstufe READ: Er kann jede Abfrage und keine Mutation ausführen, also überhaupt nichts ändern. Wenn Sie schreiben möchten, erlaubt ein READ_STOCK-Schlüssel adjustStock und sonst nichts.