Account e accesso

Un account contiene i tuoi progetti, i tuoi compagni di squadra e un modello di accesso.

Un account contiene i tuoi progetti e le persone che ci lavorano. Quando ti registri, Beeuni crea un account personale per te. Invita un collaboratore e diventa un account di team. Gli account personali e quelli di team usano gli stessi ruoli, la stessa fatturazione e gli stessi limiti.

Un unico modello di accesso

Beeuni ha un solo record di concessione: un’assegnazione. Ogni assegnazione associa un principal a un ruolo, in un determinato ambito.

Non esiste un secondo archivio delle concessioni. L’accesso di un gruppo, una concessione per risorsa e un’associazione a un ruolo personalizzato sono tutte assegnazioni. Differiscono solo per principal, oggetto e ruolo.

Ruoli dell’account

Ogni persona in un account ha un ruolo account:

• Proprietario — controllo completo, inclusi membri e fatturazione.
• Amministratore — gestisce progetti, membri, gruppi, ruoli e token.
• Membro — lavora solo nei progetti a cui è assegnato.

Proprietari e amministratori hanno accesso equivalente a quello di un gestore in ogni progetto dell’account. Un’assegnazione a un progetto non può ridurlo. Per limitare un proprietario o un amministratore in un progetto, prima cambia il suo ruolo account in membro.

L’accesso equivalente a quello di un gestore non include le sessioni private dei membri. Il proprietario di un account può abilitarlo per proprietari e amministratori con Gli amministratori possono aprire tutte le sessioni in Settings → Security. Solo un proprietario può modificarlo e ogni utilizzo viene registrato. Vedi Accesso alle sessioni.

Invita un collaboratore tramite email dalla pagina dei membri dell’account. L’invito è un’assegnazione a un principal pending. Quando l’invitato lo accetta, diventa un’assegnazione user.

Ruoli del progetto

All’interno di un progetto, un principal ha uno di due ruoli:

• Membro — visualizza il progetto, avvia e interrompe le sessioni e attiva i trigger. Non può modificare né configurare.
• Gestore — tutte le autorizzazioni del progetto: modifica il progetto, gestisce trigger, connettori, competenze, segreti e accessi, detiene le chiavi del gateway ed elimina il progetto.

Non esiste un terzo ruolo del progetto.

Il ruolo Gestore comprende l’intero insieme di autorizzazioni del progetto. Un ruolo personalizzato può solo aggiungere autorizzazioni, quindi nessun ruolo può negarne una a un gestore. Le assegnazioni agli oggetti sono il meccanismo separato che limita a quali oggetti arriva un’autorizzazione.

Imposta l’accesso al progetto dalle impostazioni di accesso del progetto oppure con beeuni access — vedi CLI.

Gruppi

Un gruppo è un principal, esattamente come una persona. Assegna un ruolo a un gruppo in un ambito e ogni membro del gruppo lo ottiene. Un gruppo aggiunge accesso, ma non rimuove mai quello già detenuto da una persona. Un gruppo fornito tramite SCIM è dello stesso tipo di principal di un gruppo creato manualmente.

Assegnazioni agli oggetti

Un’assegnazione può indicare un singolo oggetto all’interno di un progetto: un agent, un skill, un secret, un app o un trigger. Al momento Beeuni applica le assegnazioni agli oggetti per agenti e competenze.

• Per impostazione predefinita, gli agenti sono chiusi. Un membro può accedere a un agente solo quando un’assegnazione lo indica, indica uno dei suoi gruppi o indica tutti i membri del progetto.
• Per impostazione predefinita, tutti gli altri tipi di oggetto sono aperti. Se l’oggetto non ha un’assegnazione, un membro può accedervi. Un account connettore condiviso dotato di un’assegnazione può essere usato solo dalle persone indicate: vedi Scegliere chi può usare un account condiviso.
• Tutti i membri del progetto possono essere un principal. Nella finestra Grant access, seleziona Everyone in seguito dal nome del progetto per assegnare un agente a tutti i membri contemporaneamente (principal_type: "project", principal_id = l’ID del progetto). Consente solo assegnazioni agli oggetti, mai un ruolo: ogni persona mantiene il proprio ruolo nel progetto.
• Un’assegnazione a un oggetto limita anche un gestore del progetto. È questo che dà significato a «limita questo agente al gruppo Finance». Il ruolo di gestore garantisce l’accesso predefinito senza restrizioni, non un’esenzione.
• I proprietari e gli amministratori dell’account non sono mai limitati da un’assegnazione a un oggetto, né lo è un account di servizio che agisce sulle proprie assegnazioni.

Un’assegnazione a un oggetto non concede autorizzazioni proprie. Risponde a «quali oggetti?», non a «quali azioni?».

Scadenza

Imposta una expires_at su un’assegnazione e questa smetterà di concedere accesso in quel preciso istante. Il motore ignora le assegnazioni scadute. La riga rimane nel registro di controllo.

Un unico vocabolario, due associazioni

Una persona, un gruppo o un agente ottiene l’accesso da Beeuni tramite ruoli, cioè le assegnazioni descritte sopra. Un agente ha una seconda associazione separata: le autorizzazioni Beeuni dichiarate nel suo manifest in beeuni.yaml sotto agents.<name>.beeuni_permissions. Una sessione può fare solo ciò che entrambe consentono. Le due associazioni non possono ampliare l’accesso dell’altra. Un agente il cui manifest elenca project.secret.read non può comunque leggere nulla se la verifica del ruolo lo nega; allo stesso modo, un agente avviato da un proprietario non può leggere nulla se il manifest non elenca l’azione. I ruoli sono dati dell’account; le autorizzazioni Beeuni sono dati del repository nel manifest. Vedi Riferimento del manifest.

Il ruolo applicato a una sessione dell’agente è quello associato al suo account di servizio — il suo limite massimo — oppure il limite massimo predefinito per gli agenti, se non ne è associato nessuno. Il ruolo della persona che ha avviato la sessione non si applica. Un’autorizzazione, project.credentials.issue, è riservata alle persone e non viene mai concessa a un agente. Un agente concede solo ciò che detiene. Gli amministratori selezionano un agente come principal di un ruolo del progetto nell’hub Access, sotto Agents. Vedi Autorizzazioni degli agenti.

Ruoli personalizzati

Un ruolo personalizzato è un ruolo di proprietà dell’account con le autorizzazioni che scegli. Assegnarlo crea una singola assegnazione: sotto non esiste una riga di base predefinita. Un ruolo personalizzato può concedere l’accesso a un progetto senza alcun ruolo predefinito del progetto, consentendo così di creare un ruolo per reparto.

Un ruolo personalizzato può solo aggiungere autorizzazioni. Beeuni non prevede regole di negazione.

I ruoli personalizzati richiedono l’entitlement Enterprise rbac. Senza di esso, provare ad assegnarne uno restituisce 402 con code: "entitlement_required".

Super-admin

Super-admin non è un ruolo, ma un flag associato a una singola appartenenza all’account. Ignora ogni verifica delle autorizzazioni e ogni eccezione viene registrata nel registro di controllo. I ruoli sono il meccanismo per l’accesso ordinario; super-admin è la via d’uscita di emergenza sottoposta a verifica.

Chi crea l’account inizia come proprietario e super-admin. Quando un proprietario viene retrocesso, il ruolo di proprietario e il flag super-admin vengono rimossi insieme: la modifica cancella il flag e registra iam.member.super_admin.revoke. Un flag super-admin concesso a una persona che non è proprietaria rimane attivo finché un proprietario non lo revoca.

Dominio single sign-on

Un provider di identità SAML dichiara l’indirizzo email di ogni persona. Beeuni considera attendibile quell’indirizzo al di fuori dell’account solo per un dominio verificato dall’account. Fino ad allora:

• una persona che accede tramite il tuo provider di identità può comunque entrare nel tuo account e ottenere i gruppi che le spettano;
• l’identità SSO non corrisponde a un invito di un altro account e un altro account non la trova usando «aggiungi membro tramite email»;
• l’accesso SSO non unisce mai un’identità esistente con l’identità SSO;
• Enforce SSO non ha effetto e per il dominio è ancora possibile accedere con password.

Per verificare il dominio, apri Identity nelle impostazioni dell’account. La scheda SSO mostra un record DNS TXT: nome _beeuni-verification.<your-domain>, valore beeuni-verification=<token>. Pubblicalo presso il tuo provider DNS, quindi seleziona Verify domain (POST /v1/accounts/:accountId/iam/sso/provider/verify-domain). Ogni dominio può appartenere a un solo account: un dominio già verificato da un altro account non può essere verificato di nuovo. Se cambi il dominio principale, avvii una nuova verifica non ancora completata.

Con un dominio verificato e Enforce SSO attivo, il modulo di accesso web, /v1/access/check-email e gli endpoint headless /v1/auth/sign-in/password, /v1/auth/sign-in/magic-link e /v1/auth/verify-otp rifiutano le modalità di accesso con password e codice email per quel dominio (403 sso_required).

L’accesso SSO non unisce mai un proprietario o un super-admin a un’identità SSO, neanche per un dominio verificato. Mantengono la propria identità esistente e l’identità SSO entra come membro separato.

Impostazioni di accesso per funzionalità

Alcune funzionalità hanno un’impostazione di visibilità propria, oltre al modello dei ruoli:

Ognuna limita l’accesso a una singola risorsa. Nesbeeuni concede un’autorizzazione negata dalla verifica del ruolo.

API di accesso

Il catalogo è composto da dati, non da un elenco hardcoded. Ogni autorizzazione include action, scope_type, resource_type, il flag delegable, description, area, level e implies. Leggilo invece di codificare in modo hardcoded le stringhe delle azioni.

Gli endpoint di scrittura scelgono l’autorizzazione richiesta in base a ciò che vuoi concedere: project.members.manage per un ruolo di progetto o un’assegnazione a un oggetto, project.connector.connections.manage per un’assegnazione connection, member.update per un ruolo account, policy.create per un ruolo personalizzato. Non puoi aggirare un limite massimo scegliendo un endpoint diverso.

Branding

Un account Enterprise può personalizzare il marchio dell’app per tutti i membri con un logo orizzontale, un’icona quadrata e una favicon, ciascuno con una variante facoltativa per la modalità scura, oltre a un nome del prodotto che sostituisce «Beeuni» nel titolo della scheda del browser. Apri Account → Branding (/accounts/{accountId}?tab=branding). I caricamenti accettano file PNG, JPEG, WebP, SVG e ICO fino a 1 MB. Se manca il logo, viene usata l’icona; se manca la favicon, viene usata l’icona; se manca la variante scura, viene usata l’immagine chiara. Gli elementi del marchio nell’app seguono il tema dell’app; la favicon segue la combinazione di colori del sistema operativo.

Il branding segue l’account, non il browser: all’interno di un progetto, i membri vedono il marchio dell’account proprietario del progetto. Le pagine di accesso, le email e le pagine pubbliche di condivisione restano di Beeuni, perché non esiste un account da personalizzare finché non si accede. Quando l’entitlement Enterprise scade, i membri vedono di nuovo Beeuni: non viene eliminato nulla e l’account può rimuovere in qualsiasi momento gli elementi caricati.

GET /v1/accounts restituisce il valore branding effettivo per ogni account — il record, se l’entitlement è attivo, altrimenti null — così il client può visualizzarlo con una richiesta che effettua già. Nell’SDK: beeuni.accounts.branding.{get, update, uploadAsset, removeAsset, reset}.

Cambiare account

Se appartieni a più di un account, puoi passare da uno all’altro tramite il selettore degli account. Ogni account mantiene i propri progetti, membri e impostazioni.

Dispositivi connessi

Settings → Security → Devices elenca tutti i dispositivi su cui hai effettuato l’accesso: browser, app desktop e app mobile.

• Esci su un dispositivo termina subito quell’accesso. Il dispositivo non può aggiornare la sessione, il suo token smette di funzionare sugli endpoint dell’account e il telefono non riceve più notifiche push.
• Esci dagli altri dispositivi termina tutti gli altri accessi. Nessuno di essi può aggiornare la sessione e i relativi telefoni smettono immediatamente di ricevere notifiche push.

Se accedi di nuovo da un telefono, le notifiche push riprendono.

Token

Beeuni ti autentica con un token di accesso personale (beeuni_pat_...). Agisce come l’utente che lo ha creato e detiene esattamente le assegnazioni di quell’utente. Un account di servizio (beeuni_sa_...) è un principal separato, non una credenziale personale, e non ha accesso ai progetti finché un’assegnazione non glielo concede.

I due tipi si trovano in sezioni diverse, perché appartengono a proprietari diversi. Le tue chiavi API si trovano nelle tue impostazioni, in Settings → API keys (/settings/tokens): solo tu puoi vederle e smettono di funzionare quando termina la tua appartenenza. I token degli account di servizio fanno parte della configurazione dell’account e si trovano in Account → Tokens, accanto alle regole delle chiavi che ne stabiliscono la scadenza.

Vedi Autenticazione SDK per il modello completo dei token.

Registro di controllo

Il registro di controllo registra ogni richiesta che raggiunge l’API, indipendentemente dal fatto che la richiesta abbia identificato il chiamante. Il server scrive una riga per ogni richiesta HTTP, aggiornamento WebSocket, richiesta di anteprima, trasferimento Git e chiamata SCIM. La copertura non dipende dall’endpoint.

Ogni riga indica il chiamante identificato dalla richiesta:

Ogni riga registra anche la credenziale autenticata dall’API, in credential_kind e credential_id. L’ID identifica la credenziale, mai il segreto. Nell’app web viene mostrata come Via, con il nome del token o dell’app, se disponibile.

L’API non legge X-Beeuni-Client. La CLI, il server MCP e l’app web chiamano tutti la stessa API, e qualsiasi client può inviare qualsiasi valore di intestazione, quindi il log registra ciò che l’API può verificare. Le righe scritte prima del 2026-09-30 potrebbero contenere un client_reported_source autodichiarato. Le nuove righe lo lasciano vuoto. Filtra per credenziale con ?credential_kind=oauth_app su GET /v1/accounts/:accountId/audit, oppure beeuni audit ls --credential-kind oauth_app.

Le righe scritte prima del 2026-10 contengono session_sequence, integrity_previous_hash e integrity_hash: un contatore per sessione e una catena di hash. Le nuove righe lasciano vuoti tutti e tre i campi, che sono deprecati. La catena non veniva verificata e mantenerla serializzava ogni scrittura di una sessione. Il log di una sessione è ordinato per ora di creazione: prima le righe con session_sequence, in quell’ordine, poi le righe più recenti nell’ordine in cui l’API le ha create.

Una richiesta rifiutata è una riga con outcome: denied. metadata.auth registra il metodo di autenticazione del chiamante: l’ID del token, mai il segreto. Un clone Git è l’azione git.clone. Un push è git.push e metadata.refs elenca ogni ref creato, aggiornato o eliminato.

Conservazione

Le settimane vanno da lunedì alle 00 UTC a lunedì alle 00 UTC. Una settimana viene spostata nell’archivio quando il suo ultimo istante risale a 90 giorni prima; perciò un evento diventa disponibile solo tramite esportazione tra 90 e 97 giorni dopo che si è verificato. L’archivio conserva un evento fino a 365 giorni dopo la fine della sua settimana, quindi l’evento viene conservato per un totale compreso tra 365 e 372 giorni; il blocco di conservazione impedisce a chiunque, incluso il personale Beeuni, di abbreviare il periodo o eliminarlo prima. L’informativa sulla privacy indica lo stesso limite: i log dell’applicazione vengono conservati fino a 365 giorni.

L’esportazione restituisce l’archivio e PostgreSQL in un unico elenco, dal più vecchio al più recente, con gli stessi filtri, gli stessi campi e la stessa paginazione X-Audit-Next-Cursor. Entrambi i percorsi di lettura richiedono il diritto auditAccess. Gli eventi archiviati contengono gli stessi campi di quelli attivi; session_sequence e gli hash di integrità sono vuoti negli eventi scritti a partire da 2026-10 (vedi sopra).

Azioni

Ogni riga ha un action denominato domain.resource.verb e un titolo mostrato dall’app web e da beeuni audit ls:

Ogni route API ha esattamente un’azione. La riga di una richiesta mantiene il modello della route in metadata.http, mai il percorso grezzo, che potrebbe contenere un token. Quando un handler registra un proprio evento per la richiesta, includendo lo stato precedente e quello successivo, tale evento è l’unica riga della richiesta. Una richiesta che non corrisponde ad alcuna route è api.route.unmatched.

Filtra per prefisso dell’azione: ?action=iam. su GET /v1/accounts/:accountId/audit, beeuni audit ls --action iam. o --action-prefix di un webhook di audit. Azioni del log di audit elenca tutte le azioni e i relativi titoli. Le righe scritte prima del 2026-09-24 riportano METHOD /template come azione e mostrano gli stessi titoli.

I job in background di Beeuni agiscono senza una richiesta: fanno scadere le concessioni e le autorizzazioni dei tunnel, eliminano i branch delle sessioni scaduti, attivano le distribuzioni delle App e spostano i progetti tra provider di sandbox. Le loro righe riportano source: worker e metadata.auth.worker indica il job, ad esempio tunnel-cleanup o app-deployments. La riga di una distribuzione di un’App indica anche come iniziatore il membro che l’ha avviata.

Una richiesta anonima che indica uno dei tuoi progetti viene registrata nel tuo log. Seleziona queste righe con actor_type=anonymous. Le righe anonime sono soggette a limitazione della frequenza su ogni processo API, così un’ondata di richieste non può sostituire le righe attribuite. Le verifiche di integrità, le richieste CORS preflight e il traffico anonimo verso un’App distribuita non vengono registrati.

Fatturazione

Free include un progetto e 20 $ di credito iniziale, valido per 30 giorni dalla ricezione. Dal periodo successivo ricevi 2 $ al mese, senza accumulo. I crediti coprono il funzionamento del computer e i modelli ufficiali.

Il credito iniziale viene assegnato una sola volta per account personale. Chi ha già ricevuto i precedenti 2 $ riceve la differenza di 18 $; chi non li ha mai ricevuti ottiene 20 $. Creare un altro team o progetto non assegna nuovi crediti iniziali. I crediti acquistati sono conservati separatamente e non vengono cancellati alla scadenza o al rinnovo mensile dei crediti gratuiti.

La fatturazione si applica a livello di account e copre tutti i progetti dell’account. Beeuni offre un piano gratuito, un piano Pro e un piano Team con tariffazione per posto, ciascuno con accesso ai modelli e crediti specifici. Usare la propria chiave del modello non rende gratuito l’utilizzo: Beeuni applica comunque una commissione di piattaforma, tranne che nel piano gratuito.