> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Gerenciamento de Tenants (organizações e membros) > Documentação de Gerenciamento de Tenants do AgentEye (organizações e membros). Um único deployment do AgentEye atende múltiplas **organizações** (tenants) completamente isoladas, de modo que uma única instância pode hospedar times, unidades de negócio ou clientes distintos sem expor os dados de um tenant para outro. Cada linha de dados (eventos, avaliações, sessões, dashboards, consultas salvas, alertas, chaves de API e membros) pertence a exatamente uma org. O isolamento primário é aplicado no código da aplicação: cada requisição é delimitada à sua org com predicados explícitos `org_id`. No ClickHouse — onde vivem os eventos e avaliações de alto volume — isso é respaldado por uma aplicação forte no nível do motor: cada org recebe um usuário ClickHouse dedicado e somente leitura com uma política de linha por org, de modo que mesmo SQL analítico não confiável nunca consegue ler as linhas de outro tenant. No PostgreSQL, a segurança em nível de linha adiciona uma camada de defesa em profundidade no caminho de consulta somente leitura (`/queries/run`), restringindo o que esse caminho pode ver mesmo que um filtro no nível da aplicação esteja ausente; a própria conexão de escrita do servidor é executada como o proprietário da tabela e, portanto, opera pelo mesmo escopo `org_id` no nível da aplicação. O ciclo de vida do tenant é controlado pelo operador, enquanto tudo o que os membros fazem no dia a dia permanece como autoatendimento no dashboard. Organizações e suas associações são criadas e gerenciadas com a CLI **`agenteye-orgctl`**, que é distribuída dentro da imagem do servidor e executa **dentro do pod do servidor existente**. A criação e exclusão de tenants são deliberadamente mantidas fora do dashboard e da API HTTP: não há **API HTTP nem botão no dashboard** para o ciclo de vida do tenant, portanto ele fica protegido por trás do acesso ao shell do cluster/pod em vez da superfície da aplicação. Dentro de uma org, os membros trabalham inteiramente no dashboard e na API: eles fazem login, alternam entre as orgs às quais pertencem, gerenciam suas próprias chaves de API, constroem dashboards e consultas salvas, e configuram alertas para sua org. A divisão é clara: operadores provisionam e desativam tenants e seus membros via CLI; membros executam tudo dentro de um tenant pela UI. > **Deployments single-tenant não precisam de nada disso.** Uma instalação single-tenant funciona sem nenhuma ação do operador. Todos os dados, usuários e chaves vivem em uma organização `default` integrada que é provisionada automaticamente. Você só precisa deste guia quando decidir adicionar uma segunda org. *** ## Pré-requisitos Antes de criar sua **segunda** organização (a org `default` integrada não precisa de nada): * **PostgreSQL 15+.** O esquema de membros da org usa uma chave estrangeira `ON DELETE SET NULL` com lista de colunas que requer PostgreSQL 15+. Faça o upgrade do PostgreSQL antes de provisionar uma segunda org. * **Um `ORG_CH_SECRET` forte e estável.** A senha do ClickHouse de cada org é derivada como `HMAC(ORG_CH_SECRET, org_id)`, portanto o padrão de desenvolvimento integrado publicamente conhecido resultaria em credenciais por org publicamente deriváveis. `agenteye-orgctl org create` **se recusa a executar enquanto `ORG_CH_SECRET` não estiver definido ou estiver no padrão de desenvolvimento integrado**. Defina seu próprio valor primeiro (consulte [Deployment → variáveis de ambiente](/pt-br/agenteye/deployment) e, no Kubernetes, [§2.6 do guia Kubernetes](/pt-br/agenteye/kubernetes-deployment#26-multi-tenant-org-isolation-key-optional)). Mantenha-o idêntico em todas as réplicas do servidor e não o rotacione casualmente; rotacioná-lo torna órfão o usuário ClickHouse de cada org até que o próximo startup os reprovisionne. *** ## Executando a CLI `agenteye-orgctl` é distribuída na **mesma imagem que o servidor** (junto com `agenteye-server`). Você **não** faz deploy de um pod, Job ou Deployment separado para ela; você a executa dentro do pod do servidor que já está em execução, de modo que ela lê o mesmo `DATABASE_URL`, `CLICKHOUSE_URL` e `ORG_CH_SECRET` que o servidor usa. **Kubernetes:** ```bash theme={null} kubectl -n agenteye exec deploy/server -- agenteye-orgctl ``` **Docker Compose:** ```bash theme={null} docker compose exec server agenteye-orgctl ``` Os exemplos abaixo mostram o `agenteye-orgctl ` simples por brevidade; prefixe cada um com uma das duas linhas acima que corresponda ao seu deployment. *** ## Referência de comandos ### Organizações | Comando | O que faz | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `org create --slug --name ` | Cria uma nova organização. Se recusa a executar enquanto `ORG_CH_SECRET` não estiver definido ou estiver no padrão de desenvolvimento integrado (defina o seu próprio primeiro, veja Pré-requisitos). Provisiona o usuário ClickHouse somente leitura da org + política de linha. | | `org list` | Lista todas as organizações (slug, nome e estado do ciclo de vida). | | `org rename --slug --name ` | Altera o nome de exibição de uma organização. O slug (usado em URLs e chaves) permanece inalterado. | | `org delete --slug ` | **Exclusão suave** da org e remoção do seu usuário ClickHouse. Os dados são **retidos**. Isso revoga o acesso e libera a credencial ClickHouse por org, mas não apaga os eventos. Reversível por ops; primeiro passo seguro antes de uma purga. | | `org purge --slug ` | **Limpeza irreversível de dados.** A org já deve ter sido `delete`d. Nunca permitido na org `default` integrada. Use somente quando tiver certeza de que os dados do tenant devem ser destruídos. | ### Membros | Comando | O que faz | | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `member add --org --email [--set ] [--add perm1,perm2] [--remove perm3] [--protected]` | Adiciona um membro a uma org. Opcionalmente começa a partir de um conjunto de permissões integrado, depois adiciona/remove permissões individuais. `--protected` fixa o membro para que o dashboard não possa removê-lo ou rebaixá-lo (veja abaixo). O novo membro recebe um OTP no primeiro login no dashboard. | | `member list --org ` | Lista os membros da org. As colunas de saída são `EMAIL`, `SET` (o conjunto integrado do qual o membro partiu, ou `-`), `PROT` (se o membro é protegido) e `PERMISSIONS` (suas permissões efetivas). Um e-mail exibido com um `*` no final é um admin da instância; eles têm acesso a todas as orgs. | | `member update --org --email [--set ...] [--add ...] [--remove ...] [--protected \| --unprotect]` | Altera as permissões e/ou o estado de proteção de um membro. `--set` substitui a partir de um conjunto integrado; `--add` / `--remove` ajustam permissões individuais; `--protected` / `--unprotect` alternam a proteção. Passar apenas `--protected`/`--unprotect` (sem flags de concessão) altera somente a proteção e deixa as permissões existentes intactas. | | `member remove --org --email ` | Remove um membro da org. Se recusa se o membro for protegido; use `--unprotect` primeiro. (Uma pessoa pode ser membro de várias orgs; isso afeta apenas a org especificada.) | Uma pessoa pode ser membro de mais de uma org com permissões **diferentes** em cada uma, por exemplo, admin em uma org e somente leitura em outra. Cada associação é administrada de forma independente por org: conceder ou alterar as permissões de uma pessoa em uma org não tem efeito sobre sua associação em nenhuma outra. ### Membros protegidos (um admin da org irremovível) A proteção garante que uma org nunca possa acidentalmente se bloquear do autogerenciamento. Por padrão, os admins de uma org podem adicionar e remover uns aos outros pela página de usuários de autoatendimento do dashboard, de modo que poderiam remover o último admin e deixar a org sem ninguém capaz de gerenciá-la. A página de Usuários: um cartão por usuário do dashboard com seu e-mail, permissões concedidas e controles de edição/desativação Para evitar isso, marque um membro como **protegido**: ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl member add --org acme --email owner@acme.example --set admin --protected ``` Um membro protegido **não pode ser removido ou rebaixado pelo dashboard**; essas ações retornam um erro. Apenas um operador pode alterá-lo, e somente via esta CLI: execute `member update --org acme --email owner@acme.example --unprotect` primeiro, depois remova ou rebaixe. Isso garante que cada org mantenha pelo menos um admin que seus próprios membros não possam bloquear, ao mesmo tempo que mantém o controle do tenant exclusivamente para operadores. A proteção é **por org**; proteger alguém em uma org não tem efeito sobre sua associação em outra. ### Conjuntos de permissões integrados `--set` aceita um dos três conjuntos integrados, aplicados por org: | Conjunto | Destinado para | | ----------- | ---------------------------------------------------------------------------------------------------------- | | `admin` | Acesso completo dentro da org, incluindo gerenciamento de chaves de API e usuários da org. | | `standard` | Uso no dia a dia: leitura + execução de consultas, construção de dashboards, reconhecimento de incidentes. | | `read-only` | Acesso somente visualização aos dados e dashboards da org. | Comece com um conjunto usando `--set`, depois ajuste com `--add` / `--remove` usando os tokens de permissão individuais listados em [API Keys](/pt-br/agenteye/api-keys). Os próprios tokens de permissão são idênticos aos usados para chaves de API. *** ## Exemplo prático Provisione um novo tenant `acme`, adicione seu primeiro admin, deixe-o criar uma chave e, em seguida, desative a org. **1. Crie a org** (`ORG_CH_SECRET` já deve estar definido com um valor forte e estável, não indefinido ou o padrão de desenvolvimento integrado): ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl org create --slug acme --name "Acme Corp" ``` **2. Adicione o primeiro membro como admin da org:** ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl member add --org acme --email alice@acme.example --set admin ``` Alice recebe um OTP na primeira vez que faz login no dashboard. A partir daí, ela trabalha inteiramente na UI sob o prefixo de URL da sua org (ex.: `/acme/sessions`). **3. Crie uma chave de API por org (no dashboard):** O operador **não** cria chaves de dados por org pela CLI. Alice (ou qualquer membro da org com `keys:create`) cria chaves de coletor/dashboard para a org `acme` pela página de **Keys** do dashboard. Cada chave que ela cria é automaticamente marcada com sua org e só pode ler ou escrever dados da `acme`. Consulte [API Keys](/pt-br/agenteye/api-keys). **4. Ajuste um membro posteriormente:** ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl member update --org acme --email alice@acme.example --add alerts:write kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl member list --org acme ``` **5. Exclusão suave da org** (revoga o acesso + remove seu usuário ClickHouse; dados retidos): ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl org delete --slug acme ``` **6. Purga da org** (irreversível; somente após uma exclusão suave; nunca a org `default`): ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl org purge --slug acme ``` No Docker Compose, substitua cada prefixo `kubectl -n agenteye exec deploy/server --` por `docker compose exec server`. *** ## Divisão de responsabilidades Tudo o que um membro da org precisa no dia a dia é autoatendimento no dashboard e na API, com escopo automaticamente para sua org atual: * **Chaves de API por org** são criadas e gerenciadas por membros da org no dashboard (ou via API de chaves com uma chave que carrega `keys:create`). A CLI **não** cria chaves de dados. Consulte [API Keys](/pt-br/agenteye/api-keys). * **Troca de org** está integrada ao dashboard; os membros alternam entre as orgs às quais pertencem pelo seletor de org, e as páginas com escopo de org ficam em `//…`. * **Dashboards, consultas salvas, alertas e todo uso de dados** acontecem inteiramente na UI e na API, com escopo para a org atual do membro. O operador, usando `agenteye-orgctl`, é responsável apenas pelo **ciclo de vida** da org + membro: criar/renomear/excluir/purgar uma org, e adicionar/listar/atualizar/remover um membro. *** ## Veja também * [Deployment](/pt-br/agenteye/deployment): `ORG_CH_SECRET` e o restante do ambiente do servidor. * [Kubernetes Deployment](/pt-br/agenteye/kubernetes-deployment): §2.6 cria o Secret `agenteye-org-ch-secret` antes da sua primeira org multi-tenant. * [API Keys](/pt-br/agenteye/api-keys): o modelo de chave por org e os tokens de permissão usados por `--add` / `--remove`. * [Troubleshooting](/pt-br/agenteye/troubleshooting): provisionamento multi-tenant e problemas de isolamento do ClickHouse.