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:
- Melden Sie sich bei FireCustos als Administrator der Einheit an
- Öffnen Sie im Menü Verwaltung, API-Schlüssel
- 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"
- Kopieren Sie den Schlüssel sofort: Er wird nur einmal angezeigt
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:
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.read | Liste 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.write | Feuerwehrleute anlegen, bearbeiten und löschen |
Eine Anfrage außerhalb der Berechtigungen des Schlüssels liefert 403 Forbidden:
{
"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
{
"status": 401,
"title": "Unauthorized",
"detail": "Missing or invalid Authorization header."
} API-Schlüssel ist ungültig
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid API key."
} API-Schlüssel wurde widerrufen
{
"status": 401,
"title": "Unauthorized",
"detail": "API key has been revoked."
} API-Schlüssel ist abgelaufen
{
"status": 401,
"title": "Unauthorized",
"detail": "API key has expired."
}