Authentifizierung

API-Schlüssel

Schlüssel legen Sie im Dashboard unter Einstellungen → Entwickler an. Dabei wählen Sie die Berechtigungen und optional ein Ablaufdatum. Der Schlüssel hat das Format df_live_ plus 32 Zeichen und wird nur einmal angezeigt; DebtFlow speichert lediglich einen Hash. Widerrufene oder abgelaufene Schlüssel werden mit 401 invalid_api_key abgelehnt.

curl 'https://www.debt-flow.io/api/v1/me' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

OAuth 2.0

Mit OAuth verbinden andere DebtFlow-Nutzer Ihre Anwendung mit ihrem Konto, ohne Ihnen ein Passwort oder einen Schlüssel zu geben. DebtFlow unterstützt den Autorisierungscode-Ablauf mit PKCE (RFC 6749, RFC 7636) und Refresh-Tokens.

1. App registrieren

Unter Einstellungen → Apps → App registrieren geben Sie Name, Beschreibung, Website, Redirect-URIs und die höchstens anforderbaren Berechtigungen an. Sie erhalten eine Client-ID (oac_…) und – bei vertraulichen Apps – einmalig ein Client-Secret (dfs_…).

• Vertraulich: läuft auf Ihrem Server und hält das Secret geheim. Authentifizierung am Token-Endpunkt per HTTP Basic oder client_id/client_secret im Body – zusätzlich zu PKCE.
• Öffentlich: Browser-, Mobil- oder Desktop-App ohne Secret, am Token-Endpunkt nur client_id.
• PKCE (S256) ist für alle Apps Pflicht (OAuth 2.1). Ohne code_challenge lehnt DebtFlow die Autorisierung mit invalid_request ab.
• Redirect-URIs müssen exakt übereinstimmen und https:// verwenden. Für die Entwicklung ist http://localhost bzw. http://127.0.0.1 erlaubt, dort mit beliebigem Port.

2. PKCE-Werte erzeugen

Für jede Anmeldung erzeugen Sie einen zufälligen code_verifier (43–128 Zeichen) und daraus die code_challenge per SHA-256. Dazu einen zufälligen state gegen CSRF. Beide Werte bleiben bis zum Rücksprung in der Sitzung des Nutzers.

# code_verifier: 64 zufällige Zeichen aus A–Z a–z 0–9 - . _ ~
CODE_VERIFIER=$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 64)
# code_challenge = BASE64URL(SHA256(code_verifier)) ohne "="
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

3. Nutzer zur Zustimmung weiterleiten

https://www.debt-flow.io/oauth/authorize
  ?response_type=code
  &client_id=oac_DeineClientId0000000
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &scope=contacts%3Aread%20invoices%3Awrite
  &state=7Jx0…
  &code_challenge=E9Mel…
  &code_challenge_method=S256

Ist der Nutzer nicht angemeldet, meldet er sich zuerst bei DebtFlow an. Danach sieht er Ihre App, die angeforderten Rechte und die Zieladresse und erlaubt oder lehnt ab.

4. Rücksprung auswerten

Nach der Zustimmung leitet DebtFlow an Ihre Redirect-URI weiter:

https://app.example.com/oauth/callback?code=dfc_…&state=7Jx0…&iss=https%3A%2F%2Fwww.debt-flow.io

Prüfen Sie, dass state zu Ihrer Sitzung passt und iss gleich https://www.debt-flow.io ist (RFC 9207). Der Code ist 5 Minuten gültig und nur einmal einlösbar. Wird ein Code ein zweites Mal eingelöst, widerruft DebtFlow alle damit ausgestellten Tokens.

5. Code gegen Tokens tauschen

Der Token-Endpunkt erwartet application/x-www-form-urlencoded. redirect_uri ist Pflicht, wenn sie bei der Autorisierung übergeben wurde.

curl -X POST 'https://www.debt-flow.io/api/v1/oauth/token' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d code_verifier="$CODE_VERIFIER"

{
  "access_token": "dfo_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dfr_…",
  "scope": "contacts:read invoices:write"
}

6. API aufrufen

Das Access-Token wird wie ein API-Schlüssel gesendet: Authorization: Bearer dfo_…. Es gilt eine Stunde. Abgelaufene oder widerrufene Tokens liefern 401 invalid_token; fehlende Rechte 403 insufficient_scope.

7. Token erneuern

Mit dem Refresh-Token holen Sie neue Tokens. Jede Erneuerung liefert ein neues Refresh-Token; das verwendete ist danach ungültig. Optional fordern Sie mit scope weniger Rechte an, nie mehr.

curl -X POST 'https://www.debt-flow.io/api/v1/oauth/token' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

Tokens widerrufen

Beim Abmelden in Ihrer App senden Sie das Refresh-Token an den Widerrufs-Endpunkt (RFC 7009). Damit werden auch alle daraus hervorgegangenen Access-Tokens ungültig. Die Antwort ist immer 200.

curl -X POST 'https://www.debt-flow.io/api/v1/oauth/revoke' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN"

Gültigkeitsdauer

Fehler am Token-Endpunkt

Der Token- und der Widerrufs-Endpunkt antworten im OAuth-Format { "error": "…", "error_description": "…" }:

Wenn der Nutzer die Verbindung trennt

Nutzer sehen alle verbundenen Apps unter Einstellungen → Apps und können den Zugriff jederzeit widerrufen. Alle Tokens der Verbindung sind dann sofort ungültig; Ihre App erhält 401 bzw. invalid_grant und muss den Nutzer erneut durch die Autorisierung führen. Verringern Sie als Entwickler die Berechtigungen Ihrer App, gelten die geringeren Rechte sofort auch für bestehende Verbindungen.