Authentifizierung

Authentifizierung

Die ZenFlip-API unterstützt zwei Authentifizierungsmethoden: E-Mail/Passwort-Login (JWT-Tokens) und Google OAuth. API-Schlüssel für Server-zu-Server-Kommunikation sind in Kürze verfügbar. Alle geschützten Endpunkte erfordern ein gültiges Bearer-Token im Authorization-Header.

E-Mail- und Passwort-Login

Registrierung

Erstellen Sie ein neues Konto und eine Organisation:

`bash curl -X POST https://api.zenflip.io/v1/auth/signup \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com", "password": "SecureP@ssw0rd!", "name": "Alex Chen", "organizationName": "Acme Publishing" }' `

Nach der Registrierung wird eine Bestätigungs-E-Mail gesendet. Das Konto muss verifiziert werden, bevor der volle Zugriff gewährt wird.

Login

Tauschen Sie Anmeldedaten gegen JWT-Tokens ein:

`bash curl -X POST https://api.zenflip.io/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com", "password": "SecureP@ssw0rd!" }' `

Antwort:

`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600, "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "developer@example.com", "name": "Alex Chen", "role": "owner", "emailVerified": true }, "organization": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Acme Publishing", "plan": "creator" } } `

Das accessToken läuft nach der in expiresIn angegebenen Anzahl von Sekunden ab (Standard: 3600 Sekunden / 1 Stunde). Das refreshToken hat eine längere Gültigkeit und wird verwendet, um neue Zugriffstokens zu erhalten, ohne die Anmeldedaten erneut eingeben zu müssen.

Tokens verwenden

Fügen Sie das Zugriffstoken in den Authorization-Header aller geschützten Anfragen ein:

`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." `

Mit JavaScript fetch:

`javascript const response = await fetch("https://api.zenflip.io/v1/publications", { headers: { "Authorization": Bearer ${accessToken}, "Content-Type": "application/json" } }); const { data, meta } = await response.json(); `

Token-Aktualisierung

Wenn das Zugriffstoken abläuft, verwenden Sie das Refresh-Token, um ein neues Paar zu erhalten, ohne den Benutzer erneut zur Anmeldung aufzufordern:

`bash curl -X POST https://api.zenflip.io/v1/auth/refresh \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }' `

Antwort:

`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600 } `

Sowohl das Zugriffstoken als auch das Refresh-Token werden bei jedem Aktualisierungsaufruf rotiert. Speichern Sie das neue Refresh-Token und verwerfen Sie das alte. Wenn Sie das ZenFlip-Web-Dashboard verwenden, werden Tokens automatisch auch als httpOnly-Cookies gesetzt.

JavaScript-Aktualisierungsbeispiel

`javascript async function refreshAccessToken(currentRefreshToken) { const response = await fetch("https://api.zenflip.io/v1/auth/refresh", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ refreshToken: currentRefreshToken }) });

if (!response.ok) { throw new Error("Token refresh failed, user must re-authenticate"); }

const tokens = await response.json(); // Store tokens.accessToken and tokens.refreshToken securely return tokens; } `

Google OAuth

ZenFlip unterstützt Google OAuth für Single Sign-On. Dieser Ablauf ist browserbasiert und verwendet serverseitige Weiterleitungen.

Ablauf

1. Leiten Sie den Benutzer zu https://api.zenflip.io/v1/auth/google weiter.

2. Der Benutzer authentifiziert sich bei Google und erteilt seine Zustimmung.

3. Google leitet zu https://api.zenflip.io/v1/auth/google/callback weiter.

4. Die API setzt httpOnly-Authentifizierungs-Cookies und leitet den Benutzer zu Ihrer Frontend-Callback-URL weiter (z.B. https://app.zenflip.io/auth/google/callback?isNew=0).

Der isNew-Parameter gibt an, ob ein neues Konto erstellt wurde (1) oder der Benutzer sich in ein bestehendes Konto eingeloggt hat (0). Ihr Frontend liest dieses Flag, um zu entscheiden, ob das Onboarding angezeigt werden soll.

Integrationsbeispiel

`html <a href="https://api.zenflip.io/v1/auth/google" class="btn-google"> Mit Google anmelden </a> `

Nach dem OAuth-Callback hat der Browser des Benutzers Authentifizierungs-Cookies gesetzt. Nachfolgende API-Aufrufe vom Browser werden über diese Cookies authentifiziert.

API-Schlüssel (Server-zu-Server) — In Kürze verfügbar {#api-keys}

Für Backend-Integrationen, Webhooks oder CI/CD-Pipelines bieten API-Schlüssel einen einfacheren Authentifizierungspfad, der keinen Login/Refresh-Ablauf erfordert. Bis dahin verwenden Sie JWT-Tokens für den gesamten API-Zugriff.

E-Mail-Verifizierung

Neue Konten erfordern eine E-Mail-Verifizierung. Die API bietet Endpunkte zur Verifizierung und zum erneuten Senden der Bestätigungs-E-Mail:

`bash

Mit einem Token aus dem E-Mail-Link verifizieren

curl -X POST https://api.zenflip.io/v1/auth/verify-email \ -H "Content-Type: application/json" \ -d '{ "token": "verification-token-from-email" }'

Bestätigungs-E-Mail erneut senden

curl -X POST https://api.zenflip.io/v1/auth/resend-verification \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com" }' `

Passwort zurücksetzen

Wenn ein Benutzer sein Passwort vergessen hat, starten Sie den Zurücksetzungsvorgang:

`bash

E-Mail zum Zurücksetzen des Passworts anfordern

curl -X POST https://api.zenflip.io/v1/auth/forgot-password \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com" }'

Passwort mit dem Token aus der E-Mail zurücksetzen

curl -X POST https://api.zenflip.io/v1/auth/reset-password \ -H "Content-Type: application/json" \ -d '{ "token": "reset-token-from-email", "password": "NewSecureP@ssw0rd!" }' `

Aktuelles Benutzerprofil

Rufen Sie das Profil des authentifizierten Benutzers ab:

`bash curl https://api.zenflip.io/v1/auth/me \ -H "Authorization: Bearer YOUR_TOKEN" `

Abmeldung

Aktuelle Sitzung ungültig machen und Cookies löschen:

`bash curl -X POST https://api.zenflip.io/v1/auth/logout \ -H "Authorization: Bearer YOUR_TOKEN" `

Ratenlimits

Authentifizierungs-Endpunkte haben eigene Ratenlimits zur Missbrauchsprävention: