🟡 Authentifizierung

Die dataCycle API ist geschützt und erfordert – abhängig vom Nutzungsszenario – eine Authentifizierung.

Welche Methode zum Einsatz kommt, hängt davon ab, wer auf die API zugreift und aus welchem Kontext heraus.

Überblick

dataCycle unterstützt drei grundlegende Authentifizierungsarten:

Session-basierte Authentifizierung (Frontend)
Token-basierte Authentifizierung (Query-Parameter oder Header)
Basic Auth (Benutzername / Passwort)

Im Regelfall wird für externe Anwendungen und Integrationen Token- oder Bearer-Auth verwendet.

1) Session-basierte Authentifizierung (Frontend)

Wenn ein Benutzer bereits über das dataCycle-Frontend eingeloggt ist, existiert eine aktive Session.

👉 In diesem Fall ist keine zusätzliche Authentifizierung für API-Aufrufe notwendig, da die bestehende Session automatisch auch für API-Zugriffe verwendet wird.

Diese Variante ist nicht für externe Anwendungen gedacht.

2) Token-basierte Authentifizierung (empfohlen)

Für externe Zugriffe (Websites, Apps, APIs, Skripte) wird mit API-Tokens gearbeitet.

Ein Token repräsentiert dabei:

eine definierte Rolle
konkrete Berechtigungen
den Zugriff auf bestimmte Endpoints

2.1 Token als Query-Parameter

Die einfachste Variante – vor allem für Tests oder schnelle Prototypen:

curl "{BASE_URL}/api/v4/endpoints/{ENDPOINT_ID_ODER_SLUG}?token={TOKEN}"

⚠️ Hinweis: Diese Methode ist funktional, aber nicht empfohlen für produktive Systeme, da Tokens in URLs z. B. in Logs oder Browser-Historien landen können.

2.2 Bearer Token (empfohlen)

Die empfohlene Variante ist die Übergabe des Tokens über den Authorization-Header.

curl --url "{BASE_URL}/api/v4/endpoints/{ENDPOINT_ID_ODER_SLUG}" \
     --header "Authorization: Bearer {TOKEN}" \
     --header "Accept: application/json"

Vorteile:

sicherer als Query-Parameter
Standard in REST-APIs
gut geeignet für produktive Integrationen

Diese Methode wird auch im Schnellstart und in allen weiteren API-Beispielen verwendet.

3) Basic Auth (Benutzername / Passwort)

Alternativ unterstützt dataCycle auch HTTP Basic Authentication mit Benutzername (oder E-Mail-Adresse) und Passwort.

Diese Variante ist primär für:

interne Tools
Entwicklungs- oder Testumgebungen
automatisierte Skripte mit Benutzerkontext

gedacht.

⚠️ Hinweis: Für öffentliche oder langlebige Integrationen wird Token-basierte Authentifizierung klar empfohlen, da sie granularere Berechtigungen und bessere Kontrolle ermöglicht.

Berechtigungen & Zugriff

Unabhängig von der Authentifizierungsart gilt:

Tokens und Benutzer haben nur Zugriff auf freigegebene Endpoints
Ein gültiger Token bedeutet nicht automatisch Zugriff auf alle Inhalte
Fehlende Berechtigungen führen zu 403 Forbidden

👉 Details zu typischen Fehlerbildern findest du im Bereich Referenz → Fehler & Statuscodes.

Zusammengefasst

Frontend → Session, keine zusätzliche Auth nötig
Externe Zugriffe → Bearer Token verwenden
Query-Token → nur für einfache Tests
Basic Auth → Sonderfälle / Entwicklung