Authentifizierung

Die API verwendet Bearer Token zur Authentifizierung. Jede Anfrage muss einen gültigen API-Token im Authorization-Header enthalten.

Token-Format

API-Tokens haben das Format:

rfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: rfk_ (Reflecta Fördermittelkompass)
• Länge: 40 Zeichen gesamt
• Nur einmal sichtbar: Token werden bei Erstellung nur einmal angezeigt

Authorization Header

Füge bei jeder Anfrage den Token als Bearer Token hinzu:

GET /api/v1/grants HTTP/1.1
Host: foerdermittelkompass.reflecta.org
Authorization: Bearer rfk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: application/json

Token erstellen

1. Melde dich im Fördermittelkompass an
2. Navigiere zu API → Token-Verwaltung
3. Klicke auf Neuen Token erstellen
4. Vergib einen Namen (z.B. "Production", "Staging")
5. Wähle die benötigten Scopes aus
6. Wichtig: Kopiere den Token sofort – er wird nur einmal angezeigt!

Scopes

Tokens haben bestimmte Berechtigungen (Scopes):

Scope	Beschreibung	Endpoints
grants:read	Förderprogramme lesen	GET /api/v1/grants
matching:use	KI-Matching ausführen	POST /api/v1/matching
usage:read	Nutzungsstatistiken abrufen	GET /api/v1/usage/*

Ein Token kann mehrere Scopes haben. Fordere nur die Scopes an, die du wirklich benötigst.

Token widerrufen

Widerrufe Tokens, die kompromittiert wurden oder nicht mehr benötigt werden:

1. Navigiere zu API → Token-Verwaltung
2. Finde den betroffenen Token
3. Klicke auf Widerrufen

Widerrufene Tokens sind sofort ungültig. Erstelle bei Bedarf einen neuen Token.

Sicherheitsempfehlungen

Token sicher aufbewahren

• Speichere Tokens niemals im Quellcode
• Verwende Umgebungsvariablen oder Secret Manager
• Teile Tokens niemals öffentlich

# Gut: Umgebungsvariable
export FOERDERKOMPASS_API_TOKEN="rfk_..."

# Im Code
token = ENV['FOERDERKOMPASS_API_TOKEN']

Separate Tokens für Umgebungen

Erstelle separate Tokens für: - Development/Staging - Production

So kannst du bei Problemen einzelne Tokens widerrufen, ohne die Produktion zu beeinträchtigen.

Token-Rotation

Rotiere Tokens regelmäßig: 1. Erstelle einen neuen Token 2. Aktualisiere deine Anwendung 3. Widerrufe den alten Token

Fehler bei der Authentifizierung

HTTP Status	Error Code	Beschreibung
401	missing_token	Kein Authorization-Header vorhanden
401	invalid_token_format	Token hat falsches Format (muss mit rfk_ beginnen)
401	invalid_token	Token existiert nicht
401	token_revoked	Token wurde widerrufen
401	token_expired	Token ist abgelaufen
401	partner_inactive	API-Partner-Account ist deaktiviert
403	insufficient_scope	Token hat nicht die benötigte Berechtigung

Beispiel-Fehlerantwort

{
  "error": {
    "code": "invalid_token",
    "message": "The provided API token is invalid"
  }
}