Contas e acesso

Uma conta reúne seus projetos, seus colegas de equipe e um modelo de acesso.

Uma conta reúne seus projetos e as pessoas que trabalham neles. Ao se cadastrar, o Beeuni cria uma conta pessoal para você. Convide um colega de equipe e ela se torna uma conta de equipe. Contas pessoais e de equipe usam as mesmas funções, cobrança e limites.

Um modelo de acesso

O Beeuni tem um único registro de concessão: uma atribuição. Cada atribuição vincula um principal a uma função, em um escopo.

Não existe um segundo repositório de concessões. O acesso de um grupo, uma concessão por recurso e um vínculo de função personalizada são todos atribuições. Eles diferem apenas no principal, no objeto e na função.

Funções da conta

Cada pessoa em uma conta tem uma função de conta:

• Proprietário — controle total, incluindo membros e cobrança.
• Administrador — gerencia projetos, membros, grupos, funções e tokens.
• Membro — trabalha apenas nos projetos para os quais tem uma atribuição de projeto.

Proprietários e administradores têm acesso equivalente ao de gerente em todos os projetos da conta. Uma atribuição de projeto não pode reduzir esse acesso. Para limitar um proprietário ou administrador em um projeto, primeiro altere sua função de conta para membro.

O acesso equivalente ao de gerente não inclui as sessões privadas dos membros. O proprietário de uma conta pode habilitar isso para proprietários e administradores com Administradores podem abrir todas as sessões em Settings → Security. Somente um proprietário pode alterar essa opção, e cada uso é auditado. Consulte Acesso a sessões.

Convide um colega de equipe por e-mail na página de membros da conta. O convite é uma atribuição a um principal pending. Quando a pessoa aceita, ele se torna uma atribuição user.

Funções de projeto

Dentro de um projeto, um principal tem uma de duas funções:

• Membro — lê o projeto, inicia e encerra suas sessões e aciona seus gatilhos. Não pode editar nem configurar.
• Gerente — tem todas as permissões do projeto: edita o projeto, gerencia gatilhos, conectores, habilidades, segredos e acesso, detém as chaves do gateway e exclui o projeto.

Não há uma terceira função de projeto.

Gerente é o conjunto completo de permissões do projeto. Uma função personalizada só adiciona permissões, então nenhuma função pode retirar uma permissão de um gerente. Atribuições a objetos são o mecanismo separado que restringe quais objetos uma permissão alcança.

Defina o acesso ao projeto nas configurações de acesso do projeto ou com beeuni access — consulte CLI.

Grupos

Um grupo é um principal, exatamente como uma pessoa. Atribua uma função a um grupo em um escopo e todos os membros desse grupo terão essa função. Um grupo adiciona acesso. Nunca remove o acesso que uma pessoa já tem. Um grupo provisionado pelo SCIM é do mesmo tipo de principal que um grupo criado manualmente.

Atribuições a objetos

Uma atribuição pode indicar um objeto dentro de um projeto: um agent, um skill, um secret, um app ou um trigger. Atualmente, o Beeuni aplica atribuições a objetos a agentes e habilidades.

• Por padrão, agentes são restritos. Um membro só acessa um agente quando uma atribuição o identifica, identifica um de seus grupos ou identifica todas as pessoas do projeto.
• Por padrão, todos os outros tipos de objeto são abertos. Sem uma atribuição no objeto, um membro tem acesso a ele. Uma conta de conector compartilhada com uma atribuição só pode ser usada pelas pessoas que ela identifica — consulte Escolher quem pode usar uma conta compartilhada.
• Todas as pessoas do projeto também formam um principal. Na caixa de diálogo Conceder acesso, selecione Todos em seguido do nome do projeto para conceder um agente a todos os membros de uma só vez (principal_type: "project", principal_id = ID do projeto). Essa opção só comporta atribuições a objetos — nunca uma função —, então cada pessoa mantém sua própria função de projeto.
• Uma atribuição a objeto também restringe um gerente de projeto. É isso que dá significado a “limitar este agente ao grupo financeiro”. O que a função de gerente oferece é o acesso padrão sem escopo, não uma isenção.
• Proprietários e administradores da conta nunca são restringidos por uma atribuição a objeto, nem uma conta de serviço que age com base nas próprias atribuições.

Uma atribuição a objeto não inclui permissões próprias. Ela responde a “quais objetos”, não a “quais ações”.

Expiração

Defina uma expires_at para uma atribuição e ela deixará de conceder acesso nesse instante. O mecanismo ignora atribuições expiradas. A linha permanece para fins de auditoria.

Um vocabulário, dois vínculos

Uma pessoa, um grupo ou um agente recebe acesso do Beeuni por meio de funções — as atribuições descritas acima. Um agente tem um segundo vínculo separado: as permissões do Beeuni declaradas no manifesto em beeuni.yaml, dentro de agents.<name>.beeuni_permissions. Uma sessão só pode fazer o que ambos permitem. Um não amplia o outro. Um agente cujo manifesto lista project.secret.read ainda não lê nada quando a decisão da função nega o acesso, e um agente iniciado por um proprietário ainda não lê nada quando seu manifesto não lista a ação. As funções fazem parte do estado da conta; as permissões do Beeuni fazem parte do estado do repositório no manifesto. Consulte Referência do manifesto.

A função considerada para uma sessão de agente é a função vinculada à própria conta de serviço do agente — seu limite — ou o limite padrão de agente, se nenhuma função estiver vinculada. A função da pessoa que iniciou a sessão não se aplica. Uma permissão, project.credentials.issue, é exclusiva para pessoas e nunca se aplica a um agente. Um agente só concede o que tem. Os administradores selecionam um agente como principal de uma função de projeto no hub de acesso, em Agents. Consulte Permissões de agente.

Funções personalizadas

Uma função personalizada é uma função pertencente à conta, com as permissões que você escolher. Atribuí-la cria uma única atribuição — não há uma linha de função básica integrada abaixo dela. Uma função personalizada pode conceder acesso a um projeto sem nenhuma função de projeto integrada, como acontece com uma função de departamento.

Uma função personalizada só adiciona permissões. O Beeuni não tem regras de negação.

As funções personalizadas exigem a licença empresarial rbac. Sem ela, atribuir uma função personalizada retorna 402 com code: "entitlement_required".

Superadministrador

Superadministrador não é uma função. É um sinalizador em uma associação a uma conta. Ele ignora todas as verificações de permissão, e cada exceção fica registrada no log de auditoria. As funções são o mecanismo de acesso habitual; o superadministrador é a exceção de emergência auditada.

O criador da conta começa como proprietário e superadministrador. Quando um proprietário é rebaixado, a função de proprietário e o sinalizador de superadministrador são alterados juntos: a mudança limpa o sinalizador e registra iam.member.super_admin.revoke. Um sinalizador de superadministrador concedido a alguém que não é proprietário permanece até que um proprietário o revogue.

Domínio de logon único

Um provedor de identidade SAML declara o endereço de e-mail de cada pessoa. O Beeuni confia nesse endereço fora da sua conta somente para um domínio que sua conta tenha verificado. Até lá:

• uma pessoa que entra pela identidade do seu provedor ainda pode entrar na sua conta e recebe seus grupos;
• a identidade SSO dela não corresponde a nenhum convite de outra conta, e a opção “adicionar membro por e-mail” de outra conta não a encontra;
• o acesso por SSO nunca mescla uma identidade existente à identidade SSO;
• Impor SSO não tem efeito, e o acesso por senha continua funcionando para o domínio.

Para verificar o domínio, abra Identity nas configurações da conta. O cartão de SSO mostra um registro DNS TXT: nome _beeuni-verification.<your-domain>, valor beeuni-verification=<token>. Publique-o no seu provedor de DNS e selecione Verificar domínio (POST /v1/accounts/:accountId/iam/sso/provider/verify-domain). Um domínio pertence a uma única conta: não é possível verificar novamente um domínio que outra conta já verificou. Alterar o domínio principal inicia uma nova reivindicação, ainda não verificada.

Com um domínio verificado e Impor SSO ativado, o formulário de acesso à Web, /v1/access/check-email e as rotas sem interface /v1/auth/sign-in/password, /v1/auth/sign-in/magic-link e /v1/auth/verify-otp recusam o acesso por senha e código de e-mail para esse domínio (403 sso_required).

O acesso por SSO nunca mescla um proprietário ou superadministrador a uma identidade SSO, nem mesmo em um domínio verificado. Essas pessoas mantêm sua identidade existente, e a identidade SSO entra como um membro separado.

Configurações de acesso por recurso

Alguns recursos têm uma configuração própria de visibilidade, além do modelo de funções:

Cada configuração restringe o acesso a um recurso. Nenhuma concede uma permissão negada pela decisão da função.

API de acesso

O catálogo é composto por dados, não por uma lista codificada. Cada permissão traz seu action, scope_type, resource_type, sinalizador delegable, description, area, level e implies. Leia o catálogo em vez de codificar strings de ações.

As rotas de gravação escolhem a permissão exigida com base no que você está concedendo: project.members.manage para uma função de projeto ou atribuição a objeto, project.connector.connections.manage para uma atribuição connection, member.update para uma função de conta e policy.create para uma função personalizada. Não é possível contornar um limite escolhendo outra rota.

Marca

Uma conta Enterprise pode aplicar sua própria marca no app para todos os membros: um logotipo horizontal, um ícone quadrado e um favicon, cada um com uma variante opcional para o modo escuro, além de um nome de produto que substitui “Beeuni” no título da aba do navegador. Abra Account → Branding (/accounts/{accountId}?tab=branding). Os uploads aceitam PNG, JPEG, WebP, SVG e ICO de até 1 MB; se não houver logotipo, o ícone será usado; se não houver favicon, o ícone será usado; e, se faltar uma variante escura, será usada a imagem clara. Os elementos visuais no app acompanham o tema do app; o favicon acompanha o esquema de cores do sistema operacional.

A marca acompanha a conta, não o navegador: dentro de um projeto, os membros veem a marca da conta proprietária do projeto. As páginas de acesso, os e-mails e as páginas públicas de compartilhamento continuam com a marca Beeuni, pois não há uma conta a ser personalizada até alguém entrar. Quando a licença Enterprise expira, os membros voltam a ver o Beeuni — nada é excluído, e a conta pode remover a qualquer momento o que tiver carregado.

GET /v1/accounts inclui a branding efetiva de cada conta — o registro enquanto houver licença e null caso contrário — para que o cliente renderize a interface com uma única solicitação que já faz. No SDK: beeuni.accounts.branding.{get, update, uploadAsset, removeAsset, reset}.

Trocar de conta

Se você pertencer a mais de uma conta, alterne entre elas pelo seletor de contas. Cada conta mantém seus próprios projetos, membros e configurações.

Dispositivos conectados

Settings → Security → Devices lista todos os lugares em que você está conectado: navegadores, o app para desktop e o app para dispositivos móveis.

• Sair de um dispositivo encerra aquela sessão imediatamente. Ela não pode ser renovada, o token deixa de funcionar nas rotas da conta e o telefone para de receber notificações push.
• Sair de outros dispositivos encerra todas as outras sessões. Nenhuma pode ser renovada, e os telefones deixam de receber notificações push imediatamente.

Um telefone que entrar novamente voltará a receber notificações push.

Tokens

O Beeuni autentica você com um token de acesso pessoal (beeuni_pat_...). Ele age como o usuário que o criou e tem exatamente as atribuições desse usuário. Uma conta de serviço (beeuni_sa_...) é um principal separado, não uma credencial de uma pessoa, e não tem acesso a projetos até que uma atribuição o conceda.

Os dois ficam em áreas diferentes porque pertencem a proprietários diferentes. Suas próprias chaves de API ficam nas suas configurações, em Settings → API keys (/settings/tokens) — só você pode vê-las, e elas deixam de funcionar quando sua associação termina. Os tokens de contas de serviço são configurações da conta, em Account → Tokens, junto às regras de chaves que definem a expiração.

Consulte a documentação de autenticação do SDK para conhecer o modelo completo de tokens.

Log de auditoria

O log de auditoria registra toda solicitação que chega à API, tenha ou não identificado quem a fez. O servidor grava uma linha por solicitação HTTP, atualização de WebSocket, solicitação de pré-visualização, transferência Git e chamada SCIM. A cobertura não depende da rota.

Cada linha identifica o autor da solicitação que foi comprovado:

Cada linha também registra a credencial autenticada pela API em credential_kind e credential_id. O ID identifica a credencial, nunca o segredo. O app da Web mostra essa informação em Via, com o nome do token ou do app, quando disponível.

A API nunca lê X-Beeuni-Client. A CLI, o servidor MCP e o aplicativo web chamam a mesma API, e qualquer cliente pode enviar qualquer valor de cabeçalho; por isso, o log registra aquilo que a API pode comprovar. As linhas gravadas antes de 2026-09-30 podem conter um client_reported_source informado pelo próprio cliente. As novas linhas deixam esse campo vazio. Filtre por credencial com ?credential_kind=oauth_app em GET /v1/accounts/:accountId/audit ou beeuni audit ls --credential-kind oauth_app.

As linhas gravadas antes de 2026-10 contêm session_sequence, integrity_previous_hash e integrity_hash: um contador por sessão e uma cadeia de hashes. As novas linhas deixam os três campos vazios, e eles estão obsoletos. A cadeia nunca era verificada, e mantê-la serializava todas as gravações de uma sessão. O log de uma sessão é ordenado pela data de criação: primeiro vêm, nessa ordem, as linhas com session_sequence; depois, as linhas mais recentes, na ordem em que a API as criou.

Uma solicitação recusada é uma linha com outcome: denied. metadata.auth registra como o cliente se autenticou: o ID do token, nunca o segredo. Um clone do Git é a ação git.clone. Um push é git.push, e metadata.refs lista cada ref que ele criou, atualizou ou excluiu.

Retenção

As semanas vão de segunda-feira, 00 UTC, a segunda-feira, 00 UTC. Uma semana é movida para o arquivo quando seu último instante completa 90 dias; por isso, um evento passa a estar disponível somente para exportação entre 90 e 97 dias após ocorrer. O arquivo mantém um evento até 365 dias depois do fim da semana em que ocorreu. Assim, ele é mantido por 365 a 372 dias no total, e o bloqueio de retenção impede que qualquer pessoa, inclusive a equipe da Beeuni, reduza esse prazo ou o exclua antes disso. A política de privacidade estabelece o mesmo limite: os logs do aplicativo são mantidos por até 365 dias.

A exportação retorna o arquivo e o PostgreSQL em uma única lista, da mais antiga para a mais recente, com os mesmos filtros, os mesmos campos e a mesma paginação X-Audit-Next-Cursor. Os dois caminhos de leitura exigem a permissão auditAccess. Os eventos arquivados contêm os mesmos campos que os eventos ativos; session_sequence e os hashes de integridade ficam vazios nos eventos gravados desde 2026-10 (veja acima).

Ações

Cada linha tem um action chamado domain.resource.verb e um título exibido pelo aplicativo web e por beeuni audit ls:

Cada rota da API tem exatamente uma ação. A linha de uma solicitação mantém o modelo da rota em metadata.http, nunca o caminho bruto, que pode conter um token. Quando um manipulador registra o próprio evento da solicitação, com o estado anterior e o posterior, esse evento é a única linha da solicitação. Uma solicitação que não corresponde a nenhuma rota é api.route.unmatched.

Filtre por um prefixo de ação: ?action=iam. em GET /v1/accounts/:accountId/audit, beeuni audit ls --action iam. ou --action-prefix de um webhook de auditoria. Ações do log de auditoria lista todas as ações e seus títulos. As linhas gravadas antes de 2026-09-24 têm METHOD /template como ação e exibem os mesmos títulos.

Os trabalhos em segundo plano da Beeuni agem sem uma solicitação: expiram concessões e permissões de túnel, excluem ramificações de sessão expiradas, ativam implantações de App e transferem projetos entre provedores de sandbox. Suas linhas têm source: worker, e metadata.auth.worker identifica o trabalho, por exemplo, tunnel-cleanup ou app-deployments. A linha de uma implantação de App também identifica como iniciador o membro que a iniciou.

Uma solicitação anônima que menciona um de seus projetos é gravada no seu log. Selecione essas linhas com actor_type=anonymous. As linhas anônimas têm um limite de taxa em cada processo da API, para que um grande volume delas não desloque as linhas atribuídas a usuários. Verificações de integridade, solicitações preflight de CORS e tráfego anônimo para um App implantado não são registrados.

Cobrança

O plano gratuito inclui um projeto e US$ 20 em créditos iniciais, válidos por 30 dias após o recebimento. A partir do próximo período, você recebe US$ 2 por mês, sem acúmulo. Os créditos cobrem o funcionamento do computador e os modelos oficiais.

A oferta inicial é concedida uma única vez por conta pessoal. Quem já recebeu os antigos US$ 2 recebe a diferença de US$ 18; quem nunca recebeu ganha US$ 20. Criar outra equipe ou projeto não concede a oferta novamente. Créditos comprados são armazenados separadamente e não são apagados quando os créditos gratuitos expiram ou são renovados mensalmente.

A cobrança se aplica ao nível da conta e abrange todos os projetos da conta. A Beeuni oferece um plano gratuito, um plano Pro e um plano Team cobrado por assento, cada um com acesso a modelos e créditos próprios. Usar sua própria chave de modelo não torna o uso gratuito: a Beeuni ainda cobra uma taxa de plataforma além dela, exceto no plano gratuito.