Utenti, team e ruoli
L'accesso per le persone in Bird è basato sui ruoli: un utente ha un ruolo nel tuo spazio di lavoro e ogni ruolo è un insieme fisso di permessi. Non serve configurare altro; scegli il ruolo giusto e i permessi seguono.
I ruoli governano cosa possono fare le persone nella dashboard. Cosa possono fare i servizi è governato dagli scope delle chiavi API: lo stesso vocabolario di permessi, concesso per chiave anziché per ruolo.
Ruoli dello spazio di lavoro
I ruoli con cui lavori ogni giorno risiedono nello spazio di lavoro (vedi Spazio di lavoro): admin, developer e analyst. Gestiscili nella dashboard sotto Settings > Team.
Ogni permesso è una coppia {scope, level}, dove level è read o write (write include read). Un ruolo è un insieme fisso e nominato di queste coppie:
| Scope | Cosa significa write | admin | developer | analyst |
|---|---|---|---|---|
| workspace | Modificare le impostazioni dello spazio di lavoro (nome, notifiche) | write | read | read |
| api_keys | Creare e revocare chiavi API | write | write | none |
| emails | Inviare email | write | write | read |
| email_management | Gestire soppressioni e configurazione email | write | write | read |
| email_marketing | Gestire contatti, audience e broadcast | write | write | read |
| domains | Aggiungere, verificare e rimuovere domini di invio | write | write | read |
| webhooks | Configurare endpoint webhook | write | write | read |
| sms | Inviare SMS | write | write | read |
| sms_management | Gestire mittenti, soppressioni e impostazioni SMS | write | write | read |
| verify | Inviare e controllare codici di verifica | write | write | read |
| verify_management | Configurare mittenti e paesi per la verifica | write | write | read |
| Inviare messaggi WhatsApp | write | read | read | |
| whatsapp_management | Gestire template e impostazioni WhatsApp | write | write | read |
| assets | Caricare, aggiornare ed eliminare asset e cartelle | write | write | read |
| compliance | Gestire identità di registrazione, invii ed evidenze | write | write | read |
| lookup | Cercare numeri di telefono, indirizzi email e corrispondenze di identità | write | write | none |
| mailbox | Inviare e rispondere a messaggi della casella di posta | write | write | read |
| mailbox_management | Creare, aggiornare ed eliminare caselle di posta e regole di ricezione | write | write | read |
| realtime | Creare app e pubblicare eventi | write | write | read |
| voice | Leggere log delle tratte e statistiche, ed effettuare chiamate | write | write | read |
| voice_management | Gestire trunk, gateway, numeri, caller ID e destinazioni | write | write | read |
| ip_pools | Visualizzare i pool IP dell'organizzazione (sola lettura) | read | read | read |
| members | Gestire il team dello spazio di lavoro e gli inviti | write | read | read |
| analytics | Visualizzare report e analisi di recapitabilità | read | none | read |
| audit | Visualizzare il log di audit | read | none | read |
| request_logs | Visualizzare il log delle richieste (sola lettura) | read | read | read |
In pratica, un admin gestisce lo spazio di lavoro, inclusi il team e le impostazioni. Un developer può costruire integrazioni, gestire domini e webhook e creare chiavi API. Un analyst ha accesso in sola lettura.
Due righe meritano attenzione. ip_pools è in sola lettura anche per gli admin, perché l'acquisto di IP dedicati e la gestione dei pool richiede lo scope org:ip_pools:write a livello di organizzazione. Anche i permessi WhatsApp separano la gestione dalla messaggistica. Un developer può gestire template e impostazioni con whatsapp_management:write, ma può solo leggere i messaggi con whatsapp:read; l'invio resta riservato agli admin. Altri prodotti aggiungono scope usando lo stesso modello {scope, level}.
Un 403 da qualsiasi endpoint significa che il principal autenticato non ha lo {scope, level} richiesto da quell'endpoint. La soluzione è un cambio di ruolo (per una persona) o una nuova chiave con gli scope corretti (per un servizio).
Ruoli dell'organizzazione
Dietro il tuo spazio di lavoro c'è un'organizzazione che gestisce la fatturazione e l'elenco complessivo dei membri. Due ruoli governano questo livello:
- owner: tutto. Lettura e scrittura completa su operazioni di organizzazione e spazio di lavoro. Un'organizzazione può (e dovrebbe) avere più owner. La persona che ha creato l'account parte come owner.
- billing_admin: fatturazione e impostazioni dell'organizzazione (org:billing:write, org:settings:write) più accesso in lettura all'elenco dei membri dell'organizzazione e ai metadati dello spazio di lavoro. Nessun accesso alle risorse all'interno dello spazio di lavoro.
Questi ruoli servono raramente nel lavoro quotidiano: la maggior parte dei colleghi ha bisogno solo di un ruolo dello spazio di lavoro.
Membri e team
L'appartenenza è implicita: un utente fa parte "in" della tua organizzazione se ha un ruolo a livello di organizzazione o uno a livello di spazio di lavoro. Non esiste un record di appartenenza separato da gestire.
Gestisci le persone nel tuo spazio di lavoro dalla dashboard sotto Settings > Team, protetto dallo scope members dello spazio di lavoro; un admin dello spazio di lavoro gestisce il team da qui senza alcun ruolo a livello di organizzazione. La gestione del team è un'attività svolta da persone, quindi le chiavi API non possono avere lo scope members (vedi Autenticazione).
Rimuovere l'accesso allo spazio di lavoro di qualcuno rimuove quel ruolo senza modificare eventuali ruoli organizzazione che possiede. Rimuovere qualcuno dall'organizzazione revoca tutti i suoi accessi all'account. Le chiavi API che ha creato continuano a funzionare perché ogni chiave appartiene allo spazio di lavoro indipendentemente da chi l'ha creata.
Inviti
Da Settings > Team, invita un indirizzo email con un ruolo e Bird si occupa del resto. Dietro il pulsante c'è un invito intelligente: un unico flusso gestisce sia i colleghi già presenti nella tua organizzazione sia le persone che non hanno mai sentito parlare di Bird.
- Già membro dell'organizzazione: viene aggiunto immediatamente allo spazio di lavoro con il ruolo indicato. Nessuna email, nessuna attesa; la risposta è un oggetto member.
- Non ancora membro: Bird crea un invito, invia un link di registrazione via email e la risposta è un oggetto invitation con stato pending. Il link è valido per 7 giorni; dopo di che l'invito scade e devi inviarlo di nuovo.
Il campo type della risposta (team_member o invitation) indica quale caso si è verificato. Un secondo invito in sospeso per la stessa email restituisce 409 anziché creare un duplicato, e puoi ritirare un invito in sospeso in qualsiasi momento dalla stessa pagina.
Un owner può invitare un altro owner o billing_admin. Quell'invito richiede org:members:write, che solo gli owner possiedono.
Protezioni
Due invarianti vengono applicate a ogni cambio di ruolo, indipendentemente da chi lo richiede:
- L'ultimo owner non può essere rimosso. Declassare o rimuovere l'unico owner di un'organizzazione restituisce 409: un'organizzazione non può mai restare senza owner. Promuovi prima un secondo owner.
- Non puoi modificare il tuo stesso accesso. Cambiare il tuo ruolo o rimuovere te stesso restituisce 403. Questo previene sia il blocco accidentale del proprio account sia l'auto-promozione silenziosa; un altro admin o owner deve effettuare la modifica.
Come viene selezionato il contesto
Gli endpoint per membri e team esistono a due livelli, e l'organizzazione o lo spazio di lavoro a cui si rivolge una richiesta dipende da come si autentica:
- Autenticazione di sessione (la dashboard, o strumenti che agiscono per tuo conto) fornisce il contesto per ogni richiesta: X-Organization-Id sugli endpoint con scope di organizzazione, X-Workspace-Id su quelli con scope di spazio di lavoro.
- Le chiavi API portano il contesto in modo implicito. Una chiave appartiene al tuo spazio di lavoro, che fissa anche l'organizzazione; non servono header, e un header di contesto che contraddice la chiave viene rifiutato come malformato (400).
Vedi Spazio di lavoro per il modello completo di risoluzione del contesto.
Prossimi passi
- Autenticazione e chiavi API: scope per i servizi e chi può gestire le chiavi
- Spazio di lavoro: lo spazio di lavoro a cui si collegano questi ruoli
- Fatturazione e utilizzo: cosa gestiscono i ruoli di fatturazione a livello di organizzazione
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.