Authentifizierung
Wie du mit E-Mail und Passwort einen Token bekommst, ihn bei jedem Aufruf mitschickst, wie lange er gilt, die öffentlichen Routen, das Handeln im Namen eines anderen Profils und wie du ein sicheres Integrationskonto einrichtest.
Die API von Memberfy nutzt JWT-Tokens. Du tauschst E-Mail und Passwort gegen einen Token und schickst ihn bei jedem Aufruf mit. Der Token gehört einer Person (dem Konto); was sie tun darf, hängt von ihrer Rolle in der Community des jeweiligen Aufrufs ab.
Den Token holen
curl -s -X POST https://api.memberfy.net/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"dein-passwort"}'
Antwort (gekürzt):
{
"success": true,
"message": "Login successful.",
"data": {
"token": "eyJhbGciOi…",
"member": { "id": "…", "email": "[email protected]", "fullName": "Integration" }
}
}
Speichere data.token.
Den Token verwenden
Bei allen Aufrufen, die nicht öffentlich sind:
Authorization: Bearer <token>
Nur der Token, nach Bearer . Dazu fast immer der X-CommunityId.
curl -s https://api.memberfy.net/api/auth/me \
-H "Authorization: Bearer $TOKEN"
Gültigkeit
Der Token gilt 7 Tage. Ein Refresh-Token gibt es nicht: Kurz vor Ablauf meldest du dich neu an.
| Situation | Antwort |
|---|---|
| Kein Token bei einer geschützten Route | 401 · Authentication token is required |
| Ungültiger oder abgelaufener Token | 401 · Invalid or expired token |
| Token einer Person, die nicht Mitglied der Community ist | 403 · Du bist kein Mitglied dieser Community |
| Unzureichende Rolle | 403 · Benötigte Rolle (z. B. owner oder admin) und deine aktuelle Rolle |
Öffentliche Routen
Ohne Token kommen aus: Login, Registrierung, Passwort-Wiederherstellung und das Lesen dessen, was in der Community öffentlich ist (öffentliche Bereiche, die Preisseite). Bei vielen Lesezugriffen ist der Token optional: Ohne ihn kommt nur das Öffentliche; mit ihm auch das, was die Person sehen darf.
Im Namen eines anderen Profils handeln
Eigentümer, Administratoren und Moderatoren können X-ProfileId: <Profil-ID> mitschicken, um als ein anderes Profil derselben Community zu handeln (etwa um im Namen einer Person aus dem Team zu veröffentlichen). Regeln:
- Nur diese drei Rollen dürfen das; sonst kommt eine Meldung über unzureichende Berechtigungen für
X-ProfileId. - Das Profil muss zur selben Community gehören: „Profil in dieser Community nicht gefunden.“
- Niemand handelt im Namen eines Eigentümers, ohne selbst Eigentümer zu sein.
- Als ein anderes Profil zu handeln leiht nicht dessen Rolle: Es gelten weiterhin deine Berechtigungen.
Integrationskonto
Leg für eine Integration (ein CRM, eine Automatisierung) ein eigenes Mitglied an:
- Lade
[email protected]mit der kleinsten Rolle ein, die die Integration braucht: Finanzen, um Verkäufe zu lesen; Administrator, um Pläne und Produkte anzulegen. - Bewahre das Passwort in einem Secret-Store auf, nie im Code.
- Melde dich zu Beginn des Laufs an und verwende den Token bis zum Ablauf weiter.
- Ist der Token durchgesickert, ändere das Passwort des Kontos; bereits ausgestellte Tokens gelten bis zu ihrem Ablauf.
Endpunkte
POST /api/auth/login | E-Mail und Passwort → Token |
GET /api/auth/me | Wem der Token gehört |
POST /api/auth/register | Registrierung (fullName, email, password mit mindestens 8 Zeichen, einem Großbuchstaben, einem Kleinbuchstaben und einer Zahl) |
PUT /api/auth/change-password | Passwort ändern |
POST /api/auth/recovery-password | Passwort wiederherstellen |
POST /api/auth/set-password | Das Passwort über den Einladungslink festlegen (id, token, password). Antwortet mit 400 bei einem falschen Token und mit 410 bei einem bereits verwendeten oder abgelaufenen Link |
Gute Praxis
- Leg den Token nie in den Code einer öffentlichen Website: Jeder könnte ihn lesen.
- Nutze immer HTTPS (
https://api.memberfy.net). - Behandle einen
401, indem du dich einmal neu anmeldest; schlägt es wieder fehl, brich ab und schlag Alarm.