Teams-API

Teams-API

Die Teams-API ermöglicht es Ihnen, die Mitglieder Ihrer Organisation zu verwalten. Sie können neue Mitarbeiter einladen, Rollen zuweisen, Berechtigungen aktualisieren und Mitglieder entfernen. Teammitglieder-Limits werden basierend auf Ihrem Abonnementplan durchgesetzt.

Basis-URL: https://api.zenflip.io/v1/teams

Rollen und Berechtigungen

ZenFlip verwendet vier Rollen mit hierarchischen Berechtigungen:

Jede Organisation hat genau einen owner. Die Owner-Rolle kann nicht entfernt oder herabgestuft werden. Die Eigentumsübertragung muss über das Dashboard erfolgen.

Teammitglieder auflisten

Rufen Sie alle Mitglieder Ihrer Organisation ab.

` GET /teams/members `

Beispielanfrage

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

Beispielantwort

`json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "owner@example.com", "name": "Alex Chen", "role": "owner", "status": "active", "avatarUrl": "https://cdn.zenflip.io/avatars/550e8400.jpg", "emailVerified": true, "lastActiveAt": "2026-02-20T14:00:00.000Z", "createdAt": "2025-06-01T10:00:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "email": "editor@example.com", "name": "Sarah Kim", "role": "editor", "status": "active", "avatarUrl": null, "emailVerified": true, "lastActiveAt": "2026-02-19T16:30:00.000Z", "createdAt": "2025-09-15T08:00:00.000Z" }, { "id": "770e8400-e29b-41d4-a716-446655440002", "email": "newuser@example.com", "name": "Pending User", "role": "viewer", "status": "invited", "avatarUrl": null, "emailVerified": false, "lastActiveAt": null, "createdAt": "2026-02-18T11:00:00.000Z" } ] } `

Das Feld status gibt an, ob das Mitglied active (Einladung angenommen) oder invited (Annahme ausstehend) ist.

Ein Teammitglied einladen

Senden Sie eine E-Mail-Einladung an ein neues Teammitglied. Der Eingeladene erhält einen Link, um sein Passwort festzulegen und der Organisation beizutreten.

` POST /teams/invite `

Erforderliche Rolle: admin oder höher.

Anfragekörper

Beispielanfrage

`bash curl -X POST "https://api.zenflip.io/v1/teams/invite" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "neweditor@example.com", "name": "Jordan Lee", "role": "editor" }' `

Beispielantwort

`json { "data": { "id": "880e8400-e29b-41d4-a716-446655440003", "email": "neweditor@example.com", "name": "Jordan Lee", "role": "editor", "status": "invited", "createdAt": "2026-02-20T16:00:00.000Z" } } `

Wenn die Organisation das Teammitglieder-Limit ihres Plans erreicht hat, gibt die API einen 403-Fehler mit einer Nachricht zurück, die auf das erreichte Limit hinweist.

Einladung erneut senden

Senden Sie die Einladungs-E-Mail an ein ausstehendes Teammitglied erneut.

` POST /teams/members/:id/resend-invite `

Erforderliche Rolle: admin oder höher.

Beispielanfrage

`bash curl -X POST "https://api.zenflip.io/v1/teams/members/880e8400.../resend-invite" \ -H "Authorization: Bearer YOUR_TOKEN" `

Beispielantwort

`json { "message": "Invitation resent" } `

Einladung widerrufen

Stornieren Sie eine ausstehende Einladung, bevor sie angenommen wurde.

` DELETE /teams/members/:id/revoke-invite `

Erforderliche Rolle: admin oder höher.

Beispielanfrage

`bash curl -X DELETE "https://api.zenflip.io/v1/teams/members/880e8400.../revoke-invite" \ -H "Authorization: Bearer YOUR_TOKEN" `

Beispielantwort

`json { "message": "Invitation revoked" } `

Eine Einladung validieren (Öffentlich)

Prüfen Sie, ob ein Einladungstoken gültig ist, ohne ihn zu verbrauchen. Dies ist ein öffentlicher Endpunkt, der vom Frontend verwendet wird, um das Formular zur Einladungsannahme anzuzeigen.

` POST /teams/validate-invite `

Keine Authentifizierung erforderlich.

Anfragekörper

Beispielantwort

`json { "data": { "valid": true, "email": "neweditor@example.com", "organizationName": "Acme Publishing", "role": "editor", "invitedBy": "Alex Chen" } } `

Eine Einladung annehmen (Öffentlich)

Nehmen Sie eine Einladung an und legen Sie ein Passwort fest. Dieser Endpunkt erstellt das Benutzerkonto, generiert JWT-Tokens und meldet den Benutzer sofort an.

` POST /teams/accept-invite `

Keine Authentifizierung erforderlich.

Anfragekörper

Beispielanfrage

`bash curl -X POST "https://api.zenflip.io/v1/teams/accept-invite" \ -H "Content-Type: application/json" \ -d '{ "token": "invite_token_abc123", "password": "SecureP@ssw0rd!" }' `

Beispielantwort

`json { "message": "Invitation accepted successfully", "user": { "id": "880e8400-e29b-41d4-a716-446655440003", "email": "neweditor@example.com", "name": "Jordan Lee", "role": "editor" }, "organization": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Acme Publishing" }, "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600 } `

Mitgliederrolle aktualisieren

Ändern Sie die Rolle eines bestehenden Teammitglieds.

` PATCH /teams/members/:id/role `

Erforderliche Rolle: admin oder höher.

Anfragekörper

Beispielanfrage

`bash curl -X PATCH "https://api.zenflip.io/v1/teams/members/660e8400.../role" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "role": "admin" }' `

Beispielantwort

`json { "data": { "id": "660e8400-e29b-41d4-a716-446655440001", "email": "editor@example.com", "name": "Sarah Kim", "role": "admin", "status": "active" } } `

Einschränkungen:

• Sie können die owner-Rolle nicht ändern.

• Ein admin kann kein anderes Mitglied zum owner befördern.

• Sie können Ihre eigene Rolle nicht ändern.

Ein Teammitglied entfernen

Entfernen Sie ein Mitglied aus der Organisation. Dies widerruft sofort alle Zugriffsrechte.

` DELETE /teams/members/:id `

Erforderliche Rolle: admin oder höher.

Beispielanfrage

`bash curl -X DELETE "https://api.zenflip.io/v1/teams/members/660e8400-e29b-41d4-a716-446655440001" \ -H "Authorization: Bearer YOUR_TOKEN" `

Beispielantwort

`json { "message": "Team member removed" } `

Einschränkungen:

• Der Organisations-owner kann nicht entfernt werden.

• Ein Mitglied kann sich nicht selbst entfernen (verwenden Sie das Dashboard, um eine Organisation zu verlassen).

Plan-Limits

Teammitglieder-Limits variieren je nach Abonnementplan:

Der Versuch, ein Mitglied über das Plan-Limit hinaus einzuladen, gibt einen 403-Fehler zurück. Upgraden Sie Ihren Plan über die Abrechnungseinstellungen, um das Limit zu erhöhen.