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 |
access_restrictions | Gestire le allowlist IP dello spazio di lavoro | write | none | none |
api_keys | Creare e revocare chiavi API | write | write | none |
service_accounts | Esaminare e revocare le integrazioni con piattaforme connesse | 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 |
inbox_insights | Configurare Inbox Insights e visualizzare i dati di posizionamento | write | write | read |
competitive | Gestire le watchlist di Competitive Insights | write | none | 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 |
whatsapp | Inviare messaggi WhatsApp | write | write | read |
whatsapp_management | Gestire template e impostazioni WhatsApp | write | write | read |
amb | Inviare messaggi Apple Messages for Business | write | write | read |
amb_management | Gestire record aziendali, regole di instradamento e soppressioni di Apple Messages | write | write | read |
assets | Caricare, aggiornare ed eliminare asset e cartelle | write | write | read |
automations | Creare, pubblicare ed eseguire automazioni dello spazio di lavoro | write | write | read |
compliance | Gestire identità di registrazione, invii ed evidenze | write | write | read |
esim | Creare ordini eSIM e gestire le eSIM | write | write | read |
esim_credentials | Visualizzare e gestire le credenziali di installazione delle eSIM | write | write | none |
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 |
numbers | Cercare, acquistare, configurare e rilasciare numeri di telefono | write | write | read |
preferences | Registrare ed eliminare le preferenze di messaggistica su tutti i canali | 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 |
trust | Visualizzare i requisiti di attendibilità 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, le allowlist IP e le impostazioni. Un developer può costruire integrazioni su tutti i canali, gestire domini e webhook e creare chiavi API. Un analyst ha accesso in sola lettura (e nessun accesso agli scope di sola scrittura che spendono dal wallet, come lookup, né agli scope che contengono segreti, come esim_credentials).
Due righe in sola lettura meritano attenzione: ip_pools e trust sono in sola lettura a livello di spazio di lavoro anche per gli admin, perché l'acquisto di IP dedicati (org:ip_pools:write) e l'avvio delle verifiche di affidabilità dell'organizzazione (org:trust:write) sono operazioni a livello di organizzazione. Gli scope dei canali separano il traffico (emails, sms, whatsapp, amb, voice) dalla configurazione dei canali (email_management, sms_management, whatsapp_management, amb_management, voice_management). In questo modo puoi limitare con precisione gli scope delle chiavi API, anche se i ruoli dello spazio di lavoro concedono entrambi allo stesso livello.
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. Tre 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.org_admin: amministrazione dell'organizzazione (org:workspaces:write,org:master_keys:write,org:members:write,org:settings:write,org:access_restrictions:write,org:ip_pools:writeeorg:audit:read), più accessoadminautomatico in ogni spazio di lavoro dell'organizzazione.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 o un org_admin può invitare ruoli a livello di organizzazione (org:members:write). Solo un owner può concedere il ruolo owner.
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-Idsugli endpoint con scope di organizzazione,X-Workspace-Idsu 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
Continua con la documentazione, le guide e gli esempi per questo argomento.