Authentifizierung

Erfahren Sie, wie Sie Ihre API-Anfragen mit API-Schlüsseln authentifizieren.

Überblick #

Die FireCustos API verwendet API-Schlüssel-Authentifizierung. Jede Anfrage muss einen gültigen API-Schlüssel im Authorization-Header enthalten.

API-Schlüssel erstellen #

API-Schlüssel erstellt ein Administrator der Einheit in FireCustos:

  1. Melden Sie sich bei FireCustos als Administrator der Einheit an
  2. Öffnen Sie im Menü Verwaltung, API-Schlüssel
  3. Klicken Sie auf "Neuer API-Schlüssel", geben Sie einen Namen ein, an dem Sie den Zweck erkennen, und klicken Sie auf "Schlüssel erstellen"
  4. Kopieren Sie den Schlüssel sofort: Er wird nur einmal angezeigt
Important

API keys are prefixed with fc_ and are 68 characters long. The full key is displayed only once at creation — store it securely immediately.

API-Schlüssel verwenden #

Fügen Sie den API-Schlüssel im Authorization-Header als Bearer-Token ein:

bash
curl -X GET https://app.firecustos.com/api/v1/firefighters \
  -H "Authorization: Bearer fc_your_api_key_here"

Was ein Schlüssel darf #

Jeder Schlüssel trägt Berechtigungen (Scopes), die festlegen, was er darf. Ein Schlüssel ohne ausgewählte Berechtigungen kann nur lesen. Berechtigungen lassen sich jederzeit ändern und gelten ab der nächsten Anfrage.

Scope
api:firefighters.readListe der Feuerwehrleute lesen. Für jedes Mitglied: Vor- und Nachname, Telefon, E-Mail, Geburtsdatum, Dienstgrad, Mitgliedschaftsart, Funktionen, Zahl der Einsätze und Qualifikationen, ob es ein Konto hat und bis wann es nicht verfügbar ist
api:firefighters.writeFeuerwehrleute anlegen, bearbeiten und löschen

Eine Anfrage außerhalb der Berechtigungen des Schlüssels liefert 403 Forbidden:

json
{
  "status": 403,
  "title": "Forbidden",
  "detail": "You are not authorized to perform this action."
}

Sicherheit #

API-Schlüssel sind sensible Anmeldedaten. Befolgen Sie diese Best Practices:

  • Teilen Sie API-Schlüssel niemals in öffentlichen Repositories oder clientseitigem Code
  • Verwenden Sie Umgebungsvariablen zum Speichern von Schlüsseln
  • Ersetzen Sie Schlüssel von Zeit zu Zeit: Erstellen Sie einen neuen und widerrufen Sie dann den alten
  • Jeder Schlüssel wird vor dem Speichern mit SHA-256 gehasht, FireCustos speichert Ihren Schlüssel also nie im Klartext
  • Setzen Sie wenn möglich Ablaufdaten für Schlüssel

Authentifizierungsfehler #

Wenn die Authentifizierung fehlschlägt, gibt die API eine 401 Unauthorized-Antwort zurück:

Kein API-Schlüssel angegeben

json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Missing or invalid Authorization header."
}

API-Schlüssel ist ungültig

json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Invalid API key."
}

API-Schlüssel wurde widerrufen

json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "API key has been revoked."
}

API-Schlüssel ist abgelaufen

json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "API key has expired."
}