Sign inGet Started

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:

ScopeCosa significa writeadmindeveloperanalyst
workspaceModificare le impostazioni dello spazio di lavoro (nome, notifiche)writereadread
access_restrictionsGestire le allowlist IP dello spazio di lavorowritenonenone
api_keysCreare e revocare chiavi APIwritewritenone
service_accountsEsaminare e revocare le integrazioni con piattaforme connessewritewritenone
emailsInviare emailwritewriteread
email_managementGestire soppressioni e configurazione emailwritewriteread
email_marketingGestire contatti, audience e broadcastwritewriteread
inbox_insightsConfigurare Inbox Insights e visualizzare i dati di posizionamentowritewriteread
competitiveGestire le watchlist di Competitive Insightswritenoneread
domainsAggiungere, verificare e rimuovere domini di inviowritewriteread
webhooksConfigurare endpoint webhookwritewriteread
smsInviare SMSwritewriteread
sms_managementGestire mittenti, soppressioni e impostazioni SMSwritewriteread
verifyInviare e controllare codici di verificawritewriteread
verify_managementConfigurare mittenti e paesi per la verificawritewriteread
whatsappInviare messaggi WhatsAppwritewriteread
whatsapp_managementGestire template e impostazioni WhatsAppwritewriteread
ambInviare messaggi Apple Messages for Businesswritewriteread
amb_managementGestire record aziendali, regole di instradamento e soppressioni di Apple Messageswritewriteread
assetsCaricare, aggiornare ed eliminare asset e cartellewritewriteread
automationsCreare, pubblicare ed eseguire automazioni dello spazio di lavorowritewriteread
complianceGestire identità di registrazione, invii ed evidenzewritewriteread
esimCreare ordini eSIM e gestire le eSIMwritewriteread
esim_credentialsVisualizzare e gestire le credenziali di installazione delle eSIMwritewritenone
lookupCercare numeri di telefono, indirizzi email e corrispondenze di identitàwritewritenone
mailboxInviare e rispondere a messaggi della casella di postawritewriteread
mailbox_managementCreare, aggiornare ed eliminare caselle di posta e regole di ricezionewritewriteread
numbersCercare, acquistare, configurare e rilasciare numeri di telefonowritewriteread
preferencesRegistrare ed eliminare le preferenze di messaggistica su tutti i canaliwritewriteread
realtimeCreare app e pubblicare eventiwritewriteread
voiceLeggere log delle tratte e statistiche, ed effettuare chiamatewritewriteread
voice_managementGestire trunk, gateway, numeri, caller ID e destinazioniwritewriteread
ip_poolsVisualizzare i pool IP dell'organizzazione (sola lettura)readreadread
trustVisualizzare i requisiti di attendibilità dell'organizzazione (sola lettura)readreadread
membersGestire il team dello spazio di lavoro e gli invitiwritereadread
analyticsVisualizzare report e analisi di recapitabilitàreadnoneread
auditVisualizzare il log di auditreadnoneread
request_logsVisualizzare il log delle richieste (sola lettura)readreadread

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:write e org:audit:read), più accesso admin automatico 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).

Le impostazioni Team dello spazio di lavoro nella dashboard Bird, con l'elenco dei membri, il loro ruolo e l'azione di invito dei membri

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-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

Continua con la documentazione, le guide e gli esempi per questo argomento.