---
icon: key
title: Authentifizierung
description: 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

```mermaid
flowchart LR
  Admin[Organisationsadmin] --> Create[API Integrationen]
  Create --> Creds[clientId und clientSecret]
  Creds --> Header[Authorization Basic]
  Header --> API[Fuxam API v4]
  API --> Data[Institutionsdaten]
```

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](/docs/de/fuxam-web/base/user-management).
- Nach erfolgreicher Authentifizierung folgt jede Anfrage weiterhin den gemeinsamen Konventionen in der [Übersicht](/docs/de/api/overview) (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):

```http
Authorization: Basic <base64(clientId:clientSecret)>
```

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

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

Manuelle Kodierung zum Debuggen:

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

:::note
Senden Sie Zugangsdaten stets über **TLS** (`https://`). Senden Sie Basic Auth niemals über Plain HTTP.
:::

## So erhalten Sie Zugangsdaten

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

2. Gehen Sie zu **Organisation → API-Integrationen**.

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

4. 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](/docs/de/api/getting-started).

## 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.

:::warning[Keine Scopes in v4]
Gehen Sie nicht davon aus, dass ein fehlender Scope einen Schreibzugriff blockiert. Wenn sich Ihr Client authentifizieren kann, setzen Sie Least Privilege in **Ihrem** Code und Ihrer Deployment-Richtlinie durch.
:::

## 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.

:::tip
Verwenden Sie **eine Integration pro verbrauchendem System** (zum Beispiel SIS-Sync vs. BI-Export). So können Sie einen Client rotieren oder widerrufen, ohne andere zu unterbrechen, und `meta.requestId` sowie Rate-Limit-Budgets lassen sich leichter zuordnen.
:::

## 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](/docs/de/api/errors-and-idempotency) |

## 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

**[Erste Schritte](/docs/de/api/getting-started)**

Erste authentifizierte Anfrage von Ende zu Ende.

**[Fehler und Idempotenz](/docs/de/api/errors-and-idempotency)**

Problem Details, 401 vs. 404 und Rate Limits.

**[API-Übersicht](/docs/de/api/overview)**

Gemeinsame Konventionen für jeden Endpunkt.

**[Rezepte](/docs/de/api/recipes)**

Praktische Muster, die korrekte Auth voraussetzen.
