Gerencie sua equipe a partir do seu agente

Team permite que um proprietário ou administrador leia a organização e proponha mudanças a partir de um agente de programação, como Claude Code ou Codex: listar membros, consultar o log de auditoria, revogar um notebook perdido ou endurecer a política. O agente nunca aplica uma mudança por conta própria. Cada escrita se torna uma mudança pendente que uma pessoa aprova fora da conversa.

O zn-gate é uma barreira de proteção local, não um MDM. Tokens de administrador da organização dão a um agente uma forma restrita e revogável de ajudar você a administrar a organização; eles não dão à organização controle sobre a máquina de ninguém.

Crie um token de administrador da organização

1. No painel, abra Equipe → Tokens.
2. Dê um nome ao token (por exemplo laptop-claude), escolha seus escopos e uma validade de 7, 30 ou 90 dias.
3. Copie o token. Ele é exibido apenas uma vez. O zn armazena somente um hash dele, por isso não pode ser exibido novamente; se você perdê-lo, revogue-o e crie um novo.

Os tokens começam com znorg_, para que scanners de segredos e o Scrubber do zn-gate possam reconhecê-los. A parte após znorg_ até o próximo _ é o prefixo público exibido no painel e no log de atividades.

Limites:

• Até 10 tokens ativos por organização e 5 por pessoa.
• Um token funciona apenas enquanto seu criador continuar sendo proprietário ou administrador. Se essa pessoa sair da organização ou se tornar membro comum, o token deixa de funcionar imediatamente e aparece como Inativo.
• A revogação de um token tem efeito na próxima requisição e cancela suas mudanças pendentes. Proprietários e administradores podem revogar qualquer token da organização.

Escopos

Novos tokens começam com os escopos de leitura marcados. Adicione escopos de escrita somente se quiser que o agente proponha mudanças.

Um token herda os limites do seu criador: o token de um administrador não pode remover outro administrador nem alterar funções, porque os administradores também não podem fazer isso. Auditores podem criar tokens limitados a audit:read e audit:export.

Nenhum token, independentemente dos seus escopos, pode:

• alterar cobrança, assentos ou assinatura;
• criar, listar ou revogar tokens, ou alterar configurações da organização;
• criar tokens de entrada ou aceitar convites;
• aprovar ou rejeitar uma mudança pendente, inclusive a própria.

Conecte seu agente

Execute estes comandos no seu próprio terminal, não pelo agente.

# 1. Copy the token, then store it in the system keychain (read from the clipboard)
npx -y zn-gate team admin login --from-clipboard

# 2a. Claude Code
claude mcp add zn-gate -- npx -y zn-gate mcp

Para o Codex, adicione o servidor em ~/.codex/config.toml:

[mcp_servers.zn-gate]
command = "npx"
args = ["-y", "zn-gate", "mcp"]

O zn-gate team admin login verifica o token com a API e o mantém no Keychain do macOS, no Gerenciador de Credenciais do Windows ou no libsecret, fora da configuração do agente. O zn-gate team admin status mostra qual organização e token estão configurados (nunca o segredo), e o zn-gate team admin logout o remove da máquina. Revogue também o token no painel se a máquina for perdida.

As ferramentas team_* aparecem no agente somente quando um token está configurado, e apenas aquelas permitidas pelos seus escopos. ZN_LOCAL_ONLY=true as desativa.

CI e máquinas sem chaveiro

Defina ZN_ORG_TOKEN como segredo de CI ou no seu shell. Não o coloque na configuração MCP do agente (.mcp.json, ~/.codex/config.toml): o agente consegue ler esses arquivos.

export ZN_ORG_TOKEN=<paste the token here>

O que o agente pode fazer

Ferramentas de leitura: team_whoami, team_org_get, team_members_list, team_installs_list, team_policy_get, team_audit_query, team_audit_summary, team_activity_list, team_changes_list e team_change_status. A team_audit_export grava a exportação em ~/zn-exports/ e retorna apenas seu caminho, a quantidade de linhas e o SHA-256, nunca o conteúdo.

Ferramentas de escrita propõem uma mudança e retornam seu status: team_member_invite, team_invitation_revoke, team_member_remove, team_member_set_role, team_install_revoke, team_policy_propose e team_change_cancel. O token nunca aparece em resultados de ferramentas, erros ou logs; apenas o seu prefixo aparece.

Como funcionam as aprovações

Cada escrita é armazenada no servidor como uma mudança pendente com um resumo e um digest de 8 caracteres, ambos calculados pelo servidor a partir dos parâmetros. O servidor também decide a classe da mudança; o que o agente enviar é ignorado.

Mudanças que endurecem o acesso ou podem ser desfeitas (remover um membro, revogar um convite ou uma instalação, rebaixar um administrador, convidar um membro, adicionar uma regra de bloqueio, remover hosts permitidos) são confirmadas por uma pessoa, nesta ordem:

1. um formulário de confirmação exibido pelo agente, se o cliente suportar formulários de elicitação do MCP;
2. caso contrário, um diálogo nativo do sistema, em que Não é o padrão e nenhuma resposta em 2 minutos conta como não;
3. caso contrário, um link para Equipe → Aprovações no painel.

A confirmação no agente deve ocorrer em até 10 minutos. O link do painel permanece válido por 72 horas.

Mudanças que abrem acesso ou concedem privilégios (adicionar hosts ou comandos permitidos, remover ou reordenar regras, convidar um administrador ou promover alguém a administrador) são aprovadas somente no painel, em até 72 horas. A aprovação exige um login realizado nos últimos 10 minutos; se sua sessão for mais antiga, o painel pede que você faça login novamente. A concessão da função de administrador só pode ser aprovada pelo proprietário. Quando a organização usa Sempre aprovar no painel, o mesmo login recente é exigido para toda mudança proposta por um agente.

A página de aprovação mostra o resumo do servidor, o digest, qual token e cliente fizeram a solicitação e, para mudanças de política, as regras antes e depois. Uma nota escrita pelo agente é exibida por último e marcada como não verificada. Aprove somente mudanças que você solicitou e confira se o digest corresponde ao que o seu agente mostra.

O servidor verifica tudo novamente quando a mudança é aplicada: a função do criador, os escopos, a configuração da organização e a versão da política. Se a política tiver mudado nesse meio-tempo, a mudança falha e o agente precisa propô-la novamente.

Configuração da organização: mudanças pelo agente

Em Equipe → Configurações, o proprietário escolhe como as mudanças feitas pelo agente são aprovadas:

Log de atividades

Equipe → Atividade lista cada requisição feita com um token da organização, incluindo leituras, e cada mudança feita no painel. Cada entrada mostra quem agiu, se veio do painel ou via agente, o prefixo e o id do token, o cliente (por exemplo claude-code 2.1.240), a ação e seu resultado, incluindo requisições recusadas. Endereços IP não são armazenados. Abra-o a partir da linha de um token para ver apenas esse token.

Servidor MCP remoto (em breve)

Um servidor MCP hospedado em https://mcp.usezn.com/mcp, com login pela sua conta zn, está previsto para uma versão futura. Ele oferecerá as mesmas ferramentas, e toda escrita será aprovada no painel.

Limites

• Quem roubar um token pode, até que ele expire ou seja revogado, fazer no máximo mudanças do primeiro tipo: elas endurecem o acesso ou podem ser desfeitas no painel, e aparecem no log de atividades. Não podem abrir a política, conceder a função de administrador, alterar cobrança ou criar tokens. Escolha Sempre aprovar no painel se quiser que toda mudança passe por uma sessão com login.
• Uma confirmação no agente ou em um diálogo do sistema protege contra uma injeção de prompt que tente aprovar sozinha. Ela não protege contra software na máquina que possa controlar a interface do usuário.
• A aprovação só ajuda se a pessoa ler o que aprova. O resumo e o digest vêm do servidor, nunca do agente.