---

Panoramica

L'API di Gestione Utenti fornisce strumenti completi per gestire i membri del team, controllare i permessi di accesso e organizzare la tua forza lavoro attraverso i progetti e le aziende di Blue. Che tu stia aggiungendo nuovi membri al team, gestendo utenti esistenti o definendo strutture di permessi personalizzate, queste API gestiscono tutti gli aspetti della gestione del ciclo di vita degli utenti.

La gestione degli utenti in Blue opera a due livelli:

• A livello di progetto: Gestisci gli utenti all'interno di progetti specifici con permessi specifici per il progetto
• A livello aziendale: Gestisci gli utenti in tutta l'organizzazione con accesso a livello aziendale

Operazioni Disponibili

Gestione Utenti Core

Operazione	Descrizione	Link
Invite User	Invia inviti a nuovi utenti con livelli di accesso specifici	View Details →
List Users	Interroga e filtra utenti in progetti o aziende	View Details →
Remove User	Rimuovi utenti da progetti o aziende	View Details →

Gestione Ruoli e Permessi

Operazione	Descrizione	Link
Custom Roles	Crea e gestisci ruoli personalizzati con permessi granulari	View Details →

Livelli di Accesso

Blue fornisce un sistema di permessi gerarchico con livelli di accesso predefiniti:

Livelli di Accesso Standard

Livello	Descrizione	Capacità
OWNER	Controllo completo su progetto/azienda	All permissions, can transfer ownership
ADMIN	Accesso amministrativo	User management, settings, billing
MEMBER	Membro standard del team	Full project functionality, limited admin access
CLIENT	Accesso per clienti esterni	Limited project visibility, focused on deliverables
COMMENT_ONLY	Accesso solo per commenti	Può visualizzare e commentare, non può modificare
VIEW_ONLY	Accesso in sola lettura	Can view content only

Gerarchia dei Permessi

Gli utenti possono solo invitare o gestire utenti al loro livello o inferiore:

• PROPRIETARI possono gestire tutti i livelli di accesso
• AMMINISTRATORI possono gestire ADMIN, MEMBRO, CLIENTE, COMMENT_ONLY, VIEW_ONLY
• MEMBRI possono gestire MEMBRO, CLIENTE, COMMENT_ONLY, VIEW_ONLY
• CLIENTI possono solo gestire altri CLIENTI

Concetti Chiave

Inviti agli Utenti

• Basato su email: Gli utenti vengono invitati tramite indirizzo email
• Assegnazione di ruoli: Imposta il livello di accesso e un ruolo personalizzato opzionale durante l'invito
• Multi-progetto: Un singolo invito può concedere accesso a più progetti
• Scadenza: Gli inviti scadono dopo 7 giorni
• Notifiche automatiche: Blue invia automaticamente inviti via email

Accesso a Progetti vs Aziende

• Invito al progetto: Concede accesso solo a un progetto specifico
• Invito all'azienda: Concede accesso a livello aziendale, includendo opzionalmente progetti specifici
• Proprietari dell'azienda: Ottengono automaticamente accesso ADMIN a tutti i progetti aziendali
• Restrizioni di ambito: Non è possibile combinare i parametri di invito a progetto e aziendale

Ruoli Personalizzati

• Permessi granulari: Definisci capacità specifiche oltre ai livelli di accesso standard
• Specifico per progetto: I ruoli personalizzati sono limitati a progetti individuali
• Controllo a livello di campo: Controlla l'accesso a campi personalizzati specifici
• Restrizioni sulle azioni: Limita azioni specifiche (crea, modifica, elimina, ecc.)

Modelli Comuni

Invitare un Nuovo Membro del Team

mutation InviteTeamMember {
  inviteUser(input: {
    email: "john.doe@company.com"
    projectId: "web-redesign"
    accessLevel: MEMBER
  })
}

Creare un Invito a Livello Aziendale

mutation InviteToCompany {
  inviteUser(input: {
    email: "manager@company.com"
    companyId: "company_123"
    projectIds: ["project_1", "project_2", "project_3"]
    accessLevel: ADMIN
  })
}

Elencare gli Utenti del Progetto

query ProjectUsers {
  projectUsers(projectId: "web-redesign") {
    id
    user {
      name
      email
      avatar
    }
    accessLevel
    role {
      name
      permissions
    }
    invitedAt
    joinedAt
  }
}

Rimuovere un Utente

mutation RemoveProjectUser {
  removeUser(input: {
    userId: "user_456"
    projectId: "web-redesign"
  })
}

Creare un Ruolo Personalizzato

mutation CreateCustomRole {
  createProjectUserRole(input: {
    projectId: "web-redesign"
    name: "Content Reviewer"
    permissions: {
      canCreateRecords: false
      canEditOwnRecords: true
      canEditAllRecords: false
      canDeleteRecords: false
      canManageUsers: false
      canViewReports: true
    }
  }) {
    id
    name
    permissions
  }
}

Gestione dei Permessi

Matrice dei Permessi Standard

Azione	PROPRIETARIO	AMMINISTRATORE	MEMBRO	CLIENTE	COMMENT_ONLY	VIEW_ONLY
Invite Users	✅ Tutti i livelli	✅ ADMIN e inferiori	✅ MEMBRO e inferiori	✅ Solo CLIENTE	❌ No	❌ No
Remove Users	✅ Tutti gli utenti	✅ ADMIN e inferiori	✅ MEMBRO e inferiori	✅ Solo CLIENTE	❌ No	❌ No
Modify Project Settings	✅ Sì	✅ Sì	❌ No	❌ No	❌ No	❌ No
Create Records	✅ Sì	✅ Sì	✅ Sì	✅ Limitato	❌ No	❌ No
Edit All Records	✅ Sì	✅ Sì	✅ Sì	❌ No	❌ No	❌ No
Delete Records	✅ Sì	✅ Sì	✅ Sì	❌ No	❌ No	❌ No
View Reports	✅ Sì	✅ Sì	✅ Sì	✅ Limitato	❌ No	❌ No

Capacità dei Ruoli Personalizzati

• Permessi a livello di campo: Controlla l'accesso a campi personalizzati specifici
• Regole specifiche per azioni: Consenti/nega operazioni specifiche (crea, modifica, elimina)
• Restrizioni di visualizzazione: Limita quali record gli utenti possono vedere
• Attivazione/disattivazione delle funzionalità: Abilita/disabilita funzionalità specifiche per ruolo

Migliori Pratiche

Onboarding degli Utenti

1. Inizia con ruoli standard - Usa livelli di accesso predefiniti per la maggior parte degli utenti
2. Permessi progressivi - Inizia con accesso limitato, espandi secondo necessità
3. Comunicazione chiara - Includi contesto quando invii inviti
4. Revisioni regolari - Controlla periodicamente l'accesso degli utenti

Considerazioni sulla Sicurezza

1. Principio del minimo privilegio - Concedi i permessi minimi necessari
2. Audit regolari degli accessi - Rivedi i permessi degli utenti trimestralmente
3. Processo di offboarding - Rimuovi l'accesso immediatamente quando gli utenti lasciano
4. Documentazione dei ruoli personalizzati - Documenta gli scopi e le limitazioni dei ruoli personalizzati

Organizzazione del Team

1. Nomenclatura coerente - Usa nomi di ruolo chiari e descrittivi
2. Consolidamento dei ruoli - Evita di creare troppi ruoli personalizzati simili
3. Struttura aziendale - Allinea i permessi con la gerarchia organizzativa
4. Ereditarietà del progetto - Considera come i ruoli aziendali influenzano l'accesso ai progetti

Gestione degli Errori

Errori comuni nella gestione degli utenti:

Codice Errore	Descrizione	Soluzione
USER_ALREADY_IN_THE_PROJECT	L'utente ha già accesso al progetto	Check current user list before inviting
UNAUTHORIZED	Permessi insufficienti per eseguire l'azione	Verify your access level and permissions
PROJECT_NOT_FOUND	Il progetto non esiste o non si ha accesso	Confirm project ID and access rights
INVITATION_LIMIT	Raggiunto il limite di inviti per il livello di fatturazione	Upgrade plan or remove inactive users
ADD_SELF	Impossibile invitare se stessi	Usa un'email diversa o fai invitare da un altro amministratore
COMPANY_BANNED	L'account aziendale è sospeso	Contact support to resolve account status

Limiti di Frequenza

Le operazioni di gestione degli utenti hanno i seguenti limiti di frequenza:

• Inviti: 100 all'ora per azienda
• Interrogazioni utenti: 1000 all'ora per utente
• Modifiche ai ruoli: 50 all'ora per progetto

Risorse Correlate

• API Progetti - Gestione dei progetti che contengono utenti
• API Record - Comprendere come i permessi degli utenti influenzano l'accesso ai record
• API Automazioni - Automatizzare i flussi di lavoro di gestione degli utenti
• API Campi Personalizzati - Gestire i permessi a livello di campo per ruoli personalizzati