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:

In der Praxis verwaltet ein Admin den Workspace einschließlich Team, IP-Allowlists und Einstellungen. Ein Developer kann kanalübergreifend Integrationen bauen, Domains und Webhooks verwalten und API-Keys erstellen. Ein Analyst hat ausschließlich Lesezugriff (und keinen Zugriff auf reine Schreib-Scopes, die Wallet-Guthaben ausgeben, wie lookup, oder auf Scopes mit Geheimnissen wie esim_credentials).

Zwei schreibgeschützte Zeilen verdienen einen genaueren Blick: ip_pools und trust sind auf Workspace-Ebene selbst für Admins schreibgeschützt, weil der Kauf dedizierter IPs (org:ip_pools:write) und das Starten von Vertrauensverifizierungen der Organisation (org:trust:write) Vorgänge auf Organisationsebene sind. Kanal-Scopes trennen den Nachrichtenverkehr (emails, sms, whatsapp, amb, voice) von der Kanalkonfiguration (email_management, sms_management, whatsapp_management, amb_management, voice_management). So können Sie API-Keys eng begrenzen, obwohl Workspace-Rollen beides auf derselben Stufe gewähren.

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, der die Abrechnung und die gesamte Mitgliederliste gehören. Drei 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.
• org_admin: Organisationsverwaltung (org:workspaces:write, org:master_keys:write, org:members:write, org:settings:write, org:access_restrictions:write, org:ip_pools:write und org:audit:read) sowie automatischer admin-Zugriff in jedem Workspace der Organisation.
• 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, und Bird erledigt den Rest. Hinter dem Button steckt eine intelligente 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 oder org_admin kann Rollen auf Organisationsebene vergeben und dafür einladen (org:members:write). Nur ein owner kann die Rolle owner vergeben.

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