Gebruikers, teams & rollen
Toegang voor mensen in Bird is rolgebaseerd: een gebruiker heeft een rol op je werkruimte, en elke rol is een vaste set permissies. Verder hoef je niets te configureren; kies de juiste rol en de permissies volgen vanzelf.
Rollen bepalen wat mensen kunnen doen in het dashboard. Wat services kunnen doen wordt bepaald door API-key-scopes: dezelfde permissietaal, toegekend per key in plaats van per rol.
Werkruimterollen
De rollen waarmee je dagelijks werkt zitten op de werkruimte (zie Werkruimte): admin, developer en analyst. Beheer ze in het dashboard onder Settings > Team.
Elke permissie is een {scope, level}-paar, waarbij level gelijk is aan read of write (write omvat read). Een rol is een benoemde, vaste set van deze paren:
| Scope | Wat write betekent | admin | developer | analyst |
|---|---|---|---|---|
| workspace | Werkruimte-instellingen bewerken (naam, meldingen) | write | read | read |
| api_keys | API-sleutels aanmaken en intrekken | write | write | none |
| emails | E-mail verzenden | write | write | read |
| email_management | Suppressies en e-mailconfiguratie beheren | write | write | read |
| email_marketing | Contacten, doelgroepen en broadcasts beheren | write | write | read |
| domains | Verzenddomeinen toevoegen, verifiëren en verwijderen | write | write | read |
| webhooks | Webhook-endpoints configureren | write | write | read |
| sms | SMS verzenden | write | write | read |
| sms_management | SMS-afzenders, suppressies en instellingen beheren | write | write | read |
| verify | Verificatiecodes verzenden en controleren | write | write | read |
| verify_management | Verificatie-afzenders en landen configureren | write | write | read |
| WhatsApp-berichten verzenden | write | read | read | |
| whatsapp_management | WhatsApp-templates en instellingen beheren | write | write | read |
| assets | Assets en mappen uploaden, bijwerken en verwijderen | write | write | read |
| compliance | Registratie-identiteiten, inzendingen en bewijsstukken beheren | write | write | read |
| lookup | Telefoonnummers, e-mailadressen en identiteitsovereenkomsten opzoeken | write | write | none |
| mailbox | Mailboxberichten verzenden en beantwoorden | write | write | read |
| mailbox_management | Mailboxen en ontvangstregels aanmaken, bijwerken en verwijderen | write | write | read |
| realtime | Apps aanmaken en events publiceren | write | write | read |
| voice | Gesprekslogboeken en statistieken bekijken, en oproepen plaatsen | write | write | read |
| voice_management | Trunks, gateways, nummers, beller-ID's en bestemmingen beheren | write | write | read |
| ip_pools | De IP-pools van de organisatie bekijken (alleen-lezen) | read | read | read |
| members | Het werkruimteteam en uitnodigingen beheren | write | read | read |
| analytics | Rapporten en afleverstatistieken bekijken | read | none | read |
| audit | Het auditlogboek bekijken | read | none | read |
| request_logs | Het verzoeklogboek bekijken (alleen-lezen) | read | read | read |
In de praktijk beheert een admin de werkruimte, inclusief het team en de instellingen. Een developer kan integraties bouwen, domeinen en webhooks beheren en API-keys aanmaken. Een analyst heeft alleen-lezen-toegang.
Twee rijen verdienen extra aandacht. ip_pools is alleen-lezen, zelfs voor admins, omdat het aanschaffen van dedicated IP's en het beheren van pools de org:ip_pools:write-scope op organisatieniveau vereist. WhatsApp-permissies scheiden ook beheer van berichtverzending. Een developer kan templates en instellingen beheren met whatsapp_management:write, maar berichten alleen lezen met whatsapp:read; verzenden blijft beperkt tot admins. Andere producten voegen scopes toe met hetzelfde {scope, level}-model.
Een 403 van een willekeurig endpoint betekent dat de geauthenticeerde principal de {scope, level} mist die dat endpoint vereist. De oplossing is een rolwijziging (voor een persoon) of een nieuwe key met de juiste scopes (voor een service).
Organisatierollen
Achter je werkruimte zit een organisatie die facturering en de algemene ledenlijst beheert. Twee rollen beheren die laag:
- owner: alles. Volledige lees- en schrijftoegang tot organisatie- en werkruimteoperaties. Een organisatie kan (en zou moeten) meerdere owners hebben. De persoon die het account heeft aangemaakt begint als owner.
- billing_admin: facturering en organisatie-instellingen (org:billing:write, org:settings:write) plus leestoegang tot de ledenlijst van de organisatie en werkruimtemetadata. Geen toegang tot resources binnen de werkruimte.
Deze komen zelden voor in het dagelijks gebruik: de meeste teamleden hebben alleen een werkruimterol nodig.
Leden en het team
Lidmaatschap is impliciet: een gebruiker hoort bij "in" je organisatie als diegene een organisatierol of een werkruimterol heeft. Er bestaat geen apart lidmaatschapsrecord om te beheren.
Je beheert de mensen op je werkruimte in het dashboard onder Settings > Team, afgeschermd door de werkruimte-members-scope; een werkruimte-admin beheert het team hier zonder organisatierol. Teambeheer is iets wat mensen doen, dus API-keys kunnen de members-scope niet bevatten (zie Authenticatie).
Wanneer je iemands werkruimtetoegang verwijdert, verdwijnt alleen die rol; een eventuele organisatierol blijft ongewijzigd. Wanneer je iemand uit de organisatie verwijdert, vervalt al hun accounttoegang. API-keys die ze hebben aangemaakt blijven werken, omdat elke key onafhankelijk van de maker bij de werkruimte hoort.
Uitnodigingen
Nodig vanuit Settings > Team een e-mailadres uit met een rol, en Bird regelt de rest. Achter de knop zit een slimme uitnodiging: één flow werkt zowel voor collega's die al in je organisatie zitten als voor mensen die nog nooit van Bird hebben gehoord.
- Al lid van de organisatie: ze worden direct aan de werkruimte toegevoegd met de opgegeven rol. Geen e-mail, geen wachttijd; het antwoord is een member-object.
- Nog geen lid: Bird maakt een uitnodiging aan, stuurt een registratielink per e-mail, en het antwoord is een invitation-object met de status pending. De link is 7 dagen geldig; daarna verloopt de uitnodiging en nodig je ze opnieuw uit.
Het type-veld in het antwoord (team_member of invitation) vertelt je wat er is gebeurd. Een tweede openstaande uitnodiging voor hetzelfde e-mailadres retourneert 409 in plaats van een duplicaat aan te maken, en je kunt een openstaande uitnodiging op elk moment intrekken vanaf dezelfde pagina.
Een owner kan een andere owner of billing_admin uitnodigen. Die uitnodiging vereist org:members:write, die alleen owners hebben.
Beveiligingen
Twee invarianten worden afgedwongen bij elke rolwijziging, ongeacht wie het vraagt:
- De laatste owner is onverplaatsbaar. Het degraderen of verwijderen van de enige owner van een organisatie retourneert 409: een organisatie kan nooit zonder owner komen te zitten. Promoveer eerst een tweede owner.
- Je kunt je eigen toegang niet wijzigen. Het wijzigen van je eigen rol of het verwijderen van jezelf retourneert 403. Dit voorkomt zowel per ongeluk jezelf buitensluiten als stille zelfpromotie; een andere admin of owner moet de wijziging doorvoeren.
Hoe context wordt geselecteerd
Leden- en team-endpoints bestaan op twee niveaus, en welke organisatie of werkruimte een verzoek betreft hangt af van hoe het zich authenticeert:
- Sessie-auth (het dashboard, of tools die namens jou handelen) levert context per verzoek: X-Organization-Id op organisatie-scoped endpoints, X-Workspace-Id op werkruimte-scoped endpoints.
- API-keys dragen hun context impliciet mee. Een key hoort bij je werkruimte, wat ook de organisatie vastlegt; er zijn geen headers nodig, en een context-header die de key tegenspreekt wordt afgewezen als ongeldig (400).
Zie Werkruimte voor het volledige contextresolutiemodel.
Volgende stappen
- Authenticatie & API-keys: scopes voor services, en wie keys kan beheren
- Werkruimte: de werkruimte waaraan deze rollen gekoppeld zijn
- Facturering & gebruik: wat de factureringsrollen op organisatieniveau beheren
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.