API Keys

​

Permissões

Não atribuíveis a chaves. Duas permissões válidas são exclusivas para humanos/dashboard e não podem ser concedidas a uma API key: orgs:admin (administração da instância, exclusiva do operador) e keys:update. Uma requisição para POST /keys ou PATCH /keys/:id que tente conceder qualquer uma delas será rejeitada com HTTP 422. Veja a linha keys:update abaixo para entender por que uma chave bearer pode criar chaves, mas nunca editá-las.

​

Ingestão e consulta de eventos

​

Sessões e avaliações

​

Dashboards

​

Consultas salvas (compositor SQL)

​

Assistente de IA

​

API Keys

​

Usuários do dashboard

​

Configurações operacionais

​

Alertas e incidentes

​

Auditorias

Quando o recurso de Auditorias foi lançado, as concessões existentes foram ampliadas seguindo os mesmos padrões de função dos alertas: todo usuário e conjunto de permissões com alerts:read passou a ter audits:read, e todo portador de alerts:write passou a ter audits:write. As API keys existentes não foram ampliadas — conceda audits:* a uma chave explicitamente caso ela precise acessar a funcionalidade de auditoria.

Concessões armazenadas do token legado alerts:ack são interpretadas como incidents:ack, para que os responsáveis de plantão mantenham o acesso sem precisar gerar novas chaves. O token não é mais atribuível pelo editor de usuários do dashboard; a matriz oferece incidents:ack em seu lugar.

O endpoint de seleção de destinatários GET /alerts/recipients (que lista os emails dos membros que um editor de alerta pode notificar) é acessível por quem possui alerts:read ou alerts:write, de modo que os editores de alertas podem preencher o seletor sem precisar de users:read.

Um visualizador de dashboards precisa de dashboards:read (para carregar as views salvas) e evaluations:read (as métricas de saúde são calculadas a partir de dados de avaliação). Conceda dashboards:write para permitir que um usuário crie ou edite dashboards, e dashboards:delete para removê-los.

/health e /auth/* (solicitação de OTP, verificação de OTP, verificação de sessão, logout) não requerem autenticação por design; fazem parte do fluxo de login e do probe de liveness. GET /access-granters exige uma chave válida, mas nenhuma permissão específica, de modo que qualquer usuário autenticado pode ver quais administradores contatar sobre mudanças de acesso.

​

Conjuntos de Permissões

• DEFAULT_USER_PERMISSIONS (a concessão pré-selecionada quando um admin abre + novo usuário) tem como padrão o conjunto standard. Veja Deployment.
• A flag --set no agenteye-orgctl (gerenciamento de membros pelo operador) inicia um membro a partir de um conjunto nomeado, que você pode ajustar com --add / --remove. Veja Tenant Management.

Quando um conjunto inclui uma permissão não atribuível a chaves (por exemplo, um conjunto personalizado com keys:update), ao inicializar uma chave a partir desse conjunto, os tokens não atribuíveis são descartados; caso contrário, o servidor rejeitaria a chave com HTTP 422. Usuários do dashboard não estão sujeitos a essa restrição.

​

Chave Admin de Bootstrap

​

Escopo de organização

​

Criando Chaves

​

Chave de coletor (somente ingestão)

curl -s -X POST http://your-server:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-collector",
    "key": "your-collector-secret",
    "permissions": ["events:add"]
  }'

​

Chave de dashboard (somente leitura)

curl -s -X POST http://your-server:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dashboard",
    "key": "your-dashboard-secret",
    "permissions": ["events:read", "keys:read"]
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "prod-collector",
  "permissions": ["events:add"],
  "created_at": "2026-04-01T12:00:00Z"
}

​

Listando Chaves

curl -s http://your-server:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY"

​

Desabilitando uma Chave

curl -s -X POST http://your-server:8080/keys/<id>/disable \
  -H "Authorization: Bearer $ADMIN_KEY"

​

Regenerando uma Chave

curl -s -X POST http://your-server:8080/keys/<id>/regenerate \
  -H "Authorization: Bearer $ADMIN_KEY"

​

Gerenciamento de Chaves no Dashboard

​

Layout de Chaves Recomendado

Chave do assistente. A chave do assistente é inicializada automaticamente pelo servidor a partir da variável de ambiente AGENT_API_KEY (o mesmo segredo que o agente apresenta como AGENTEYE_API_KEY); não há etapa manual de criação de chave nem envolvimento da chave admin. Suas permissões são fixadas no código-fonte para que o escopo não possa ser ampliado por configuração incorreta: leitura de eventos/avaliações/dashboards, mais escrita em dashboards e leitura/escrita/execução de consultas para o fluxo de criação de consultas via IA. Todo SQL ainda passa pelo mesmo papel somente leitura e pelas verificações do sql_guard que uma consulta escrita por um usuário, portanto isso amplia a superfície de criação, não a superfície de dados; operações destrutivas (queries:delete, dashboards:delete) são deliberadamente mantidas fora da chave do assistente. Assim como a chave admin, ela é protegida: não pode ser desabilitada ou regenerada pela API de chaves, apenas rotacionada alterando AGENT_API_KEY e reiniciando. Usuários do dashboard também precisam da permissão agent:use para ver e usar o assistente. Se você habilitar a auto-instrumentação, forneça ao assistente uma chave separada somente com events:add.