Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

Authentifizierung

HTTP Basic Auth für die Fuxam API v4 — clientId und clientSecret, Lebenszyklus der Zugangsdaten, Alles-oder-nichts-Zugriff und Sicherheits-Best Practices.

Jede Anfrage an die Fuxam API v4 authentifiziert sich mit HTTP Basic Auth über clientId und clientSecret einer Integration. Es gibt in v4 kein separates Session-Cookie, keinen OAuth-Bearer-Token und keinen eigenen API-Key-Header pro Anfrage — der Authorization-Header ist die gesamte Authentifizierungsfläche.

Warum das wichtig ist

API-Zugangsdaten sind institutionelle Macht. Ein durchgesickerter clientSecret ermöglicht einem Angreifer, dieselben Daten zu lesen und zu ändern wie Ihre Integration — denn v4 implementiert keine Berechtigungs-Scopes für Basic Auth. Saubere Handhabung der Zugangsdaten — Erstellung, Speicherung, Rotation und minimale Exposition — ist ebenso wichtig wie korrekter Anfragecode.

Wie es zusammenhängt

Die Authentifizierung ist wie folgt mit dem Produkt verknüpft:

  • Zugangsdaten werden unter Organisation → API-Integrationen in Fuxam Web erstellt.
  • Die Integration handelt für die Institution, nicht als benannter Mitarbeiter aus der Nutzerverwaltung.
  • Nach erfolgreicher Authentifizierung folgt jede Anfrage weiterhin den gemeinsamen Konventionen in der Übersicht (Envelope, Paginierung, Fehler).

Schlüsselkonzepte

Begriff Definition
Integration Ein registrierter API-Client für Ihre Institution.
clientId Öffentliche Kennung der Integration (der Basic-Auth-„Benutzername“).
clientSecret Vertrauliches Geheimnis (das Basic-Auth-„Passwort“).
Basic Auth Standard-Header Authorization: Basic mit Base64-kodiertem clientId:clientSecret.
Alles-oder-nichts v4 implementiert keine API-Key-Berechtigungs-Scopes — authentifizierte Integrationen haben vollen Integrationszugriff.

So funktioniert Basic Auth

Kodieren Sie die Zugangsdaten als Base64 der Zeichenkette clientId:clientSecret (ohne zusätzliche Leerzeichen):

Authorization: Basic <base64(clientId:clientSecret)>

Beispiel mit curl (bevorzugt — lässt curl für Sie kodieren):

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=1"

Manuelle Kodierung zum Debuggen:

printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n'

So erhalten Sie Zugangsdaten

Melden Sie sich in Fuxam Web mit einem Konto an, das Organisationseinstellungen verwalten darf.

Gehen Sie zu Organisation → API-Integrationen.

Erstellen Sie eine neue Integration und kopieren Sie clientId und clientSecret in Ihren Secrets-Store.

Prüfen Sie mit einem einfachen Lesezugriff wie GET /users?limit=1, bevor Sie die Zugangsdaten in Produktionsjobs einbinden.

Für eine vollständige Walkthrough des ersten Aufrufs siehe Erste Schritte.

Alles-oder-nichts-Zugriff

API-Key-Berechtigungs-Scopes sind in v4 nicht implementiert. Basic Auth ist für die Integration Alles-oder-nichts:

  • Es gibt keinen dokumentierten Weg, einen „nur-lesen“-API-Key über Scopes auszustellen.
  • Behandeln Sie jede Integration so, als könne sie jede Operation ausführen, die die API Integrationen bereitstellt.
  • Reduzieren Sie das Risiko, indem Sie einschränken, wer Integrationen erstellen darf, Zugangsdaten pro System isolieren und Clients schreiben, die nur die benötigten Endpunkte aufrufen.

Zugangsdaten rotieren und ersetzen

Planen Sie die Rotation wie bei Datenbankpasswörtern:

  1. Erstellen Sie eine neue Integration (oder holen Sie ein neues Secret, wenn Ihr Prozess das Secret an derselben Integration ersetzt).
  2. Aktualisieren Sie jeden Verbraucher (CI, Middleware, Serverless-Env) auf die neuen Zugangsdaten.
  3. Bestätigen Sie, dass der Produktionsverkehr mit dem neuen Paar erfolgreich ist.
  4. Nehmen Sie die alten Zugangsdaten außer Betrieb oder löschen Sie sie, damit sie sich nicht mehr authentifizieren können.

Sicherheits-Best Practices

Praxis Empfehlung
Secret-Speicherung Bewahren Sie clientSecret in einem Secrets-Manager oder verschlüsselten Env-Store auf. Committen Sie es niemals in git und fügen Sie es nicht in Tickets ein.
Least Privilege (betrieblich) Auch ohne API-Scopes: Geben Sie Zugangsdaten nur an die Dienste weiter, die sie brauchen; trennen Sie Integrationen pro Workload.
Nur TLS Rufen Sie ausschließlich https://fuxam.app auf. Lehnen Sie Redirects zu Nicht-TLS-URLs in HTTP-Clients ab.
Sorgfältig loggen Loggen Sie meta.requestId und Statuscodes; loggen Sie niemals den Authorization-Header oder das Roh-Secret.
Bei Personalwechsel rotieren Wenn jemand mit Zugang zum Secret ausscheidet, rotieren Sie die Zugangsdaten.
Bei Leak widerrufen Wenn ein Secret exponiert sein könnte, deaktivieren oder ersetzen Sie die Integration sofort und prüfen Sie den jüngsten Verkehr.

Häufige Fallstricke

Fallstrick Was passiert Lösung
Handgemachtes Base64 mit Zeilenumbrüchen Intermittierendes 401 Zeilenumbrüche entfernen oder -u / Bibliotheks-Basic-Auth nutzen
Secrets in Mobile- oder Browser-Apps einbetten Jeder kann sie extrahieren Rufen Sie die API nur von vertrauenswürdigen serverseitigen Komponenten auf
Eine Integration über viele Teams teilen Schwer zu rotieren; laute Rate Limits Pro System aufteilen
403 für unautorisierte Ressourcen annehmen v4 sendet nie 403 bei Cross-Tenant-Ablehnung Erwarten Sie 404 resource_not_found — siehe Fehler und Idempotenz

FAQ

Gibt es OAuth2 oder Personal Access Tokens in v4?

Dieses Handbuch dokumentiert HTTP Basic Auth mit Integrations-clientId und clientSecret als Authentifizierungsmethode für v4. Nutzen Sie dieses Muster, sofern Ihre Institution keine anderen Anweisungen erhält.

Braucht jeder Mitarbeiter eigene API-Zugangsdaten?

Nein. Integrationen authentifizieren die Institutionsintegration, nicht ein einzelnes Nutzerverwaltungskonto. Mitarbeitende nutzen weiterhin Fuxam Web mit ihren eigenen Rollen; Middleware verwendet die Integrations-Zugangsdaten.

Welcher Statuscode bedeutet falsche Zugangsdaten?

Fehlgeschlagene Authentifizierung liefert typischerweise 401. Zwischen „falsches Passwort“ und „unbekannter Client“ zu unterscheiden, sollten Clients nicht weiter als „Zugangsdaten prüfen“ bei 401 erwarten.

Verwandte Seiten

War diese Seite hilfreich?