---
title: "Contas e acesso"
description: "Uma conta reúne seus projetos, seus colegas de equipe e um modelo de acesso."
---
Uma conta reúne seus [projetos](/docs/pt/project) 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.
| Termo | Significado |
|---|---|
| **Principal** | Quem tem o acesso. Um `user`, um `group`, um `service_account` (a identidade de um agente) ou o e-mail de um convidado `pending`. |
| **Função** | Um conjunto nomeado de permissões. O Beeuni oferece as funções integradas abaixo. Uma conta pode adicionar funções personalizadas. |
| **Permissão** | Uma ação, por exemplo `project.secret.read` ou `member.update`. |
| **Escopo** | Onde a função se aplica: a `account` inteira ou um único `project`. |
| **Objeto** | Opcional. Restringe a atribuição a um único `agent`, `skill`, `secret`, `app` ou `trigger` dentro do escopo. |
| **Expiração** | Opcional. A atribuição deixa de conceder acesso em `expires_at`. |
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](/docs/pt/work/sessions#admins-can-open-every-session).
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](#object-assignments) 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](/docs/pt/cli#access).
## 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](/docs/pt/connect/connectors#choose-who-can-use-a-shared-account).
- **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..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](/docs/pt/project/manifest#agents).
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](/docs/pt/project/permissions).
## 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.`, valor `beeuni-verification=`. 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:
| Configuração | Define |
|---|---|
| [Modo de acesso ao app](/docs/pt/feature-flags/apps#access-modes) | Quem pode abrir um App implantado |
| [Acesso às sessões do gatilho](/docs/pt/connect/triggers#session-access) | Quem pode abrir as sessões criadas por um gatilho |
| [Política de canais do Slack](/docs/pt/connect/slack) | Quem pode iniciar uma sessão em um canal |
| [Recursos do computador](/docs/pt/connect/computers#what-the-computer-allows) | Quais chamadas de sistema de arquivos, shell e desktop um computador conectado aceita |
Cada configuração restringe o acesso a um recurso. Nenhuma concede uma permissão negada pela decisão da função.
## API de acesso
| Método + caminho | Função |
|---|---|
| `GET /v1/accounts/{accountId}/iam/assignments` | Lista atribuições. Filtra por principal, escopo, objeto ou função. |
| `POST /v1/accounts/{accountId}/iam/assignments` | Cria uma atribuição. |
| `DELETE /v1/accounts/{accountId}/iam/assignments/{assignmentId}` | Revoga uma atribuição. |
| `GET /v1/accounts/{accountId}/iam/permissions` | O catálogo de permissões, como dados. |
| `GET /v1/accounts/{accountId}/iam/roles` | Funções integradas e personalizadas. |
| `GET /v1/accounts/{accountId}/iam/roles/{roleId}/permissions` | As permissões de uma função. |
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.
| Método + caminho | Função |
|---|---|
| `GET /v1/accounts/{accountId}/branding` | O registro armazenado e se o plano permite usá-lo. |
| `PUT /v1/accounts/{accountId}/branding` | Define ou limpa `app_name`. Exige `account.write` e a licença `branding` (caso contrário, retorna `402 entitlement_required`). |
| `POST /v1/accounts/{accountId}/branding/assets/{kind}` | Envia uma imagem como `file` multipart. `kind` pode ser `logo`, `icon`, `favicon` ou suas variantes `_dark`. Está sujeita à mesma restrição de `PUT`. |
| `DELETE /v1/accounts/{accountId}/branding/assets/{kind}` | Remove uma imagem. Somente `account.write`. |
| `DELETE /v1/accounts/{accountId}/branding` | Restaura tudo para Beeuni. Somente `account.write`. |
`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:
| `actor_type` | Autor |
| --- | --- |
| `human` | Uma pessoa conectada ou o token de uma pessoa (`source: api_key`). |
| `agent` | A credencial de agente de uma sessão. A linha também identifica a pessoa em nome de quem o agente age. |
| `service_account` | Um token de conta de serviço. |
| `system` | Uma chave de API da conta, um token de diretório SCIM, um webhook de integração com assinatura verificada ou uma tarefa em segundo plano do Beeuni (`source: worker`). |
| `anonymous` | Uma solicitação sem credenciais ou com uma credencial inválida ou falsificada. |
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.
| `credential_kind` | Credencial | `credential_id` |
| --- | --- | --- |
| `browser_session` | Uma sessão de login do Beeuni (o aplicativo web ou um cliente com um JWT de login). | O ID da sessão de login. |
| `personal_access_token` | Um token de acesso pessoal, como o da CLI. | O ID do token. |
| `oauth_app` | O token `beeuni_oat_` de um aplicativo conectado, como um cliente MCP. | O ID do cliente OAuth. |
| `session_token` | O próprio token de uma sessão de agente. | O ID da sessão. |
| `api_key` | Uma chave de API da conta. | O ID da chave. |
| `service_account` | Um token de conta de serviço. | O ID da conta de serviço. |
| `scim_token` | Um token de diretório SCIM. | O ID do token. |
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
| Idade do evento | Onde fica armazenado | Como consultar |
| --- | --- | --- |
| 0 a 90 dias | PostgreSQL, uma partição por semana | O log de auditoria no aplicativo web, `GET /v1/accounts/:accountId/audit`, `beeuni audit ls`, webhooks de auditoria e exportação |
| 90 a 365 dias | Um arquivo S3 com Object Lock (modo de conformidade) | Somente por exportação: `GET /v1/accounts/:accountId/audit/export` ou `beeuni audit export` |
| Mais de 365 dias | Excluído | Indisponível |
As semanas vão de segunda-feira, 00:00 UTC, a segunda-feira, 00: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`:
| Ação | Título | Gerada por |
| --- | --- | --- |
| `gateway.key.revoke` | Chave do gateway LLM revogada | Uma solicitação a `DELETE /v1/projects/:projectId/gateway/keys/:keyId`. |
| `iam.group.create` | Grupo criado | A solicitação que criou o grupo. A linha inclui o novo grupo em `after`. |
| `secret.consumer.used` | Segredo usado | Um sandbox que leu um segredo. |
| `api.rate_limit.exceeded` | Limite de taxa da API atingido | Um limitador que recusou uma solicitação. `metadata.limiter` o identifica. |
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](/docs/pt/audit-actions) 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.
:::info[Empresarial]
Login único (`sso`), provisionamento SCIM (`scim`), funções personalizadas (`rbac`) e acesso à auditoria (`auditAccess`) são permissões do plano empresarial. Uma permissão é independente de uma função: ela determina se o recurso está disponível para a conta, enquanto a função continua determinando quem pode usá-lo. Entre em contato com a equipe de vendas para habilitá-las.
:::