Benutzer, Teams & Rollen
Der Zugriff für Personen in Bird ist rollenbasiert: Ein Benutzer hat eine Rolle in Ihrem Workspace, und jede Rolle ist ein fester Satz von Berechtigungen. Weitere Konfiguration ist nicht nötig – wählen Sie die richtige Rolle, und die Berechtigungen ergeben sich daraus.
Rollen bestimmen, was Personen im Dashboard tun können. Was Dienste tun können, wird durch API-Key-Scopes gesteuert: dasselbe Berechtigungsvokabular, pro Key statt pro Rolle vergeben.
Workspace-Rollen
Die Rollen, mit denen Sie täglich arbeiten, gehören zum Workspace (siehe Workspace): admin, developer und analyst. Verwalten Sie sie im Dashboard unter Settings > Team.
Jede Berechtigung ist ein {scope, level}-Paar, wobei level entweder read oder write ist (write schließt read ein). Eine Rolle ist ein benannter, fester Satz dieser Paare:
| Scope | Bedeutung von write | admin | developer | analyst |
|---|---|---|---|---|
| workspace | Workspace-Einstellungen bearbeiten (Name, Benachrichtigungen) | write | read | read |
| api_keys | API-Schlüssel erstellen und widerrufen | write | write | none |
| emails | E-Mail senden | write | write | read |
| email_management | Suppressions und E-Mail-Konfiguration verwalten | write | write | read |
| email_marketing | Kontakte, Zielgruppen und Broadcasts verwalten | write | write | read |
| domains | Versanddomains hinzufügen, verifizieren und entfernen | write | write | read |
| webhooks | Webhook-Endpunkte konfigurieren | write | write | read |
| sms | SMS senden | write | write | read |
| sms_management | SMS-Absender, Suppressions und Einstellungen verwalten | write | write | read |
| verify | Bestätigungscodes senden und prüfen | write | write | read |
| verify_management | Verifizierungsabsender und Länder konfigurieren | write | write | read |
| WhatsApp-Nachrichten senden | write | read | read | |
| whatsapp_management | WhatsApp-Vorlagen und -Einstellungen verwalten | write | write | read |
| assets | Assets und Ordner hochladen, aktualisieren und löschen | write | write | read |
| compliance | Registrierungsidentitäten, Einreichungen und Nachweise verwalten | write | write | read |
| lookup | Telefonnummern, E-Mail-Adressen und Identitätsabgleiche nachschlagen | write | write | none |
| mailbox | Postfachnachrichten senden und beantworten | write | write | read |
| mailbox_management | Postfächer und Empfangsregeln erstellen, aktualisieren und löschen | write | write | read |
| realtime | Apps erstellen und Events veröffentlichen | write | write | read |
| voice | Leg-Logs und Statistiken lesen und Anrufe tätigen | write | write | read |
| voice_management | Trunks, Gateways, Nummern, Anrufer-IDs und Ziele verwalten | write | write | read |
| ip_pools | IP-Pools der Organisation anzeigen (schreibgeschützt) | read | read | read |
| members | Workspace-Team und Einladungen verwalten | write | read | read |
| analytics | Berichte und Zustellbarkeitsanalysen anzeigen | read | none | read |
| audit | Audit-Log anzeigen | read | none | read |
| request_logs | Request-Log anzeigen (schreibgeschützt) | read | read | read |
In der Praxis verwaltet ein Admin den Workspace einschließlich Team und Einstellungen. Ein Developer kann Integrationen bauen, Domains und Webhooks verwalten und API-Keys erstellen. Ein Analyst hat ausschließlich Lesezugriff.
Zwei Zeilen verdienen einen genaueren Blick. ip_pools ist selbst für Admins schreibgeschützt, weil der Kauf dedizierter IPs und die Verwaltung von Pools den Scope org:ip_pools:write auf Organisationsebene erfordert. Die Berechtigungen für WhatsApp trennen außerdem Verwaltung von Nachrichtenversand. Ein Developer kann Vorlagen und Einstellungen mit whatsapp_management:write verwalten, Nachrichten aber nur mit whatsapp:read lesen; das Senden bleibt Admins vorbehalten. Weitere Produkte fügen Scopes nach demselben {scope, level}-Modell hinzu.
Ein 403 von einem beliebigen Endpunkt bedeutet, dass dem authentifizierten Prinzipal der {scope, level} fehlt, den dieser Endpunkt erfordert. Die Lösung ist eine Rollenänderung (für eine Person) oder ein neuer Key mit den richtigen Scopes (für einen Dienst).
Organisationsrollen
Hinter Ihrem Workspace steht eine Organisation, die Abrechnung und die gesamte Mitgliederliste besitzt. Zwei Rollen verwalten diese Ebene:
- owner: alles. Vollständiger Lese- und Schreibzugriff auf Organisations- und Workspace-Operationen. Eine Organisation kann (und sollte) mehrere Owner haben. Die Person, die das Konto erstellt hat, startet als Owner.
- billing_admin: Abrechnung und Organisationseinstellungen (org:billing:write, org:settings:write) plus Lesezugriff auf die Mitgliederliste der Organisation und Workspace-Metadaten. Kein Zugriff auf Ressourcen innerhalb des Workspace.
Diese Rollen werden im Alltag selten benötigt: Die meisten Teammitglieder brauchen nur eine Workspace-Rolle.
Mitglieder und das Team
Mitgliedschaft ist implizit: Ein Benutzer gehört "in" Ihrer Organisation an, wenn er eine Organisationsrolle oder eine Workspace-Rolle hat. Es gibt keinen separaten Mitgliedschaftsdatensatz, den Sie verwalten müssen.
Sie verwalten die Personen in Ihrem Workspace im Dashboard unter Settings > Team, geschützt durch den Workspace-Scope members; ein Workspace-Admin verwaltet das Team hier ohne eine Rolle auf Organisationsebene. Teamverwaltung ist eine Aufgabe für Personen, deshalb können API-Keys den Scope members nicht besitzen (siehe Authentication).
Wenn Sie jemandem den Workspace-Zugriff entziehen, wird nur diese Rolle entfernt, ohne eine vorhandene Organisationsrolle zu ändern. Wird jemand aus der Organisation entfernt, verliert die Person sämtlichen Kontozugriff. API-Keys, die sie erstellt hat, funktionieren weiterhin, weil jeder Key unabhängig von seinem Ersteller zum Workspace gehört.
Einladungen
Laden Sie unter Settings > Team eine E-Mail-Adresse mit einer Rolle ein – Bird erledigt den Rest. Hinter dem Button steckt eine smarte Einladung: Ein einziger Ablauf deckt sowohl Kolleginnen und Kollegen ab, die bereits in Ihrer Organisation sind, als auch Personen, die Bird noch nicht kennen.
- Bereits Mitglied der Organisation: Die Person wird sofort mit der angegebenen Rolle zum Workspace hinzugefügt. Keine E-Mail, kein Warten; die Antwort ist ein Member-Objekt.
- Noch kein Mitglied: Bird erstellt eine Einladung, sendet einen Registrierungslink per E-Mail, und die Antwort ist ein Invitation-Objekt mit dem Status pending. Der Link ist 7 Tage gültig; danach läuft die Einladung ab, und Sie laden die Person erneut ein.
Das Feld type der Antwort (team_member oder invitation) zeigt an, welcher Fall eingetreten ist. Eine zweite ausstehende Einladung für dieselbe E-Mail-Adresse gibt 409 zurück, statt ein Duplikat zu erzeugen, und Sie können eine ausstehende Einladung jederzeit auf derselben Seite zurückziehen.
Ein Owner kann einen weiteren owner oder billing_admin einladen. Diese Einladung erfordert org:members:write, und nur Owner besitzen diesen Scope.
Schutzmechanismen
Zwei Invarianten werden bei jeder Rollenänderung durchgesetzt, unabhängig davon, wer sie anfordert:
- Der letzte Owner ist unveränderbar. Herabstufen oder Entfernen des einzigen Owners einer Organisation gibt 409 zurück: Eine Organisation darf niemals ohne Owner enden. Befördern Sie zuerst einen zweiten Owner.
- Sie können Ihren eigenen Zugriff nicht ändern. Das Ändern Ihrer eigenen Rolle oder das Entfernen Ihrer selbst gibt 403 zurück. Das verhindert sowohl versehentliche Selbstaussperrung als auch stille Selbstbeförderung; ein anderer Admin oder Owner muss die Änderung vornehmen.
Wie der Kontext bestimmt wird
Mitglieder- und Team-Endpunkte existieren auf zwei Ebenen, und welche Organisation oder welchen Workspace eine Anfrage anspricht, hängt von der Authentifizierung ab:
- Session-Auth (das Dashboard oder Tools, die in Ihrem Namen handeln) liefert den Kontext pro Anfrage: X-Organization-Id bei organisationsbezogenen Endpunkten, X-Workspace-Id bei workspacebezogenen.
- API-Keys tragen ihren Kontext implizit. Ein Key gehört zu Ihrem Workspace, wodurch auch die Organisation festgelegt ist; Header sind nicht nötig, und ein Kontext-Header, der dem Key widerspricht, wird als fehlerhaft abgelehnt (400).
Siehe Workspace für das vollständige Kontextauflösungsmodell.
Nächste Schritte
- Authentication & API-Keys: Scopes für Dienste und wer Keys verwalten kann
- Workspace: der Workspace, dem diese Rollen zugeordnet sind
- Billing & Usage: was die Abrechnungsrollen auf Organisationsebene verwalten
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.