Chaves de API

As chaves de API controlam quem e o que pode acessar seu servidor de Observabilidade do Failproof AI, permitindo que um coletor envie eventos sem nunca obter poderes de leitura ou administração. Cada chave carrega uma ou mais permissões, e cada permissão controla rotas específicas do servidor; você concede apenas as que uma tarefa precisa. A maioria das implantações cria apenas três tipos de chave.

Os 3 tipos de chaves que a maioria das implantações precisa

Chave	Permissões	Quem usa
Chave de coletor	`events:add`	O `agenteye-collector` em cada máquina de agente, para enviar eventos.
Chave de leitura do painel	`events:read`, `keys:read`	Um operador somente leitura ou integração que consulta dados sem modificá-los.
Chave admin de bootstrap	todas as permissões	O operador que inicializa a instância pela primeira vez (e o painel). Originada da variável de ambiente `ADMIN_KEY`. Veja Chave admin de bootstrap.

Comece por aqui. Consulte o catálogo completo de permissões abaixo somente quando precisar de uma chave mais restrita com escopo personalizado. Veja também Layout recomendado de chaves e Criando chaves.

Permissões

O servidor aplica um catálogo fixo de permissões; cada uma controla rotas HTTP específicas. Uma chave admin possui todas elas; uma chave com escopo possui o subconjunto que você concede na criação. Strings de permissão desconhecidas são rejeitadas ao criar uma chave.

Nota: Duas permissões válidas são exclusivas para humanos/painel e não podem ser concedidas a uma chave de API: orgs:admin (administração da instância, que é exclusiva do operador) e keys:update. Uma requisição a POST /keys ou PATCH /keys/:id que tente conceder qualquer uma delas é 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

Permissão	Rotas HTTP	O que permite
`events:add`	`POST /events`	Ingerir lotes de eventos de um coletor. A única permissão que um coletor precisa.
`events:read`	`GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export`	Consultar eventos, listar os ambientes conhecidos, listar os identificadores de modelos vistos nos dados (usados pela visualização de Modelos e filtros de modelo), calcular o agregado de latência que alimenta o mapa de calor / banda de percentil, e exportar uma sessão como JSONL. Os endpoints de faceta da barra de filtros compartilhada `GET /events/environments` e `GET /events/agent_ids` são acessíveis com either `events:read` or `evaluations:read`, portanto a página de sessões (protegida por `evaluations:read`) reutiliza a mesma faceta por organização. `GET /events/models` não é um deles: requer `events:read`, então um principal com apenas `evaluations:read` recebe 403.

Sessões e avaliações

Permissão	Rotas HTTP	O que permite
`evaluations:read`	`GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs`	Listar sessões, ler resultados de avaliações, a saúde consolidada das avaliações usada pelos painéis e o estado da fila do worker de jobs de avaliação.
`evaluations:trigger`	`POST /sessions/:session_id/re-evaluate`	Enfileirar manualmente uma reavaliação para uma sessão concluída.

Painéis

Permissão	Rotas HTTP	O que permite
`dashboards:read`	`GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles`	Listar painéis, carregar um e ler seus tiles.
`dashboards:write`	`POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout`	Criar e editar painéis, adicionar / editar / remover tiles e reordenar o grid de tiles.
`dashboards:delete`	`DELETE /dashboards/:id`	Excluir um painel inteiro (a exclusão em nível de tile fica em `dashboards:write`).

Consultas salvas (compositor SQL)

Permissão	Rotas HTTP	O que permite
`queries:read`	`GET /queries`, `GET /queries/:id`, `GET /queries/schema`	Listar consultas salvas, carregar uma e inspecionar o esquema somente leitura que o compositor usa.
`queries:write`	`POST /queries`, `PUT /queries/:id`	Criar e editar consultas salvas. O SQL ainda é roteado pelo mesmo papel somente leitura e pelas verificações SQL protegidas de uma chamada `queries:run`.
`queries:delete`	`DELETE /queries/:id`	Excluir uma consulta salva.
`queries:run`	`POST /queries/run`	Executar SQL salvo ou ad-hoc contra o papel somente leitura usado pelo compositor.

Assistente de IA

Permissão	Rotas HTTP	O que permite
`agent:use`	`GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages`	Conversar com o assistente de IA e gerenciar suas próprias conversas (privadas). Necessário para o usuário ver o dock do assistente; a própria chave do assistente é `dashboard-assistant` e é inicializada separadamente (veja abaixo).

Permissão	Rotas HTTP	O que permite
`keys:create`	`POST /keys`	Criar uma nova chave de API com escopo. Não concede a edição das permissões de uma chave existente (isso é `keys:update`).
`keys:read`	`GET /keys`	Listar chaves existentes. Segredos nunca são retornados por esse endpoint.
`keys:update`	`PATCH /keys/:id`	Editar as permissões de uma chave existente. Uma permissão exclusiva para humanos/painel; não pode ser atribuída a uma chave de API (uma chave bearer pode criar chaves, mas nunca editá-las).
`keys:disable`	`POST /keys/:id/disable`	Revogar uma chave. Chaves protegidas (`admin`, `dashboard-assistant`) não podem ser desativadas; rotacione-as via variável de ambiente + reinicialização.
`keys:regenerate`	`POST /keys/:id/regenerate`	Rotacionar o segredo de uma chave. Chaves protegidas não podem ser regeneradas por esta rota.

Usuários do painel

Permissão	Rotas HTTP	O que permite
`users:create`	`POST /users`, `GET /users/defaults`	Convidar um novo usuário do painel (envia um e-mail + login com senha de uso único (OTP)) e ler o conjunto de permissões padrão configurado no painel usado para pré-preencher o formulário de convite.
`users:read`	`GET /users`, `GET /users/:id`	Listar usuários e carregar um registro de usuário individual.
`users:update`	`PUT /users/:id`	Editar as permissões de um usuário. As atualizações enviam um e-mail de alteração de permissão ao usuário afetado e entram em vigor na próxima requisição; nenhum relogin é necessário.
`users:delete`	`DELETE /users/:id`, `POST /users/:id/enable`	Desativar um usuário (revoga suas sessões imediatamente) e reativar um usuário anteriormente desativado.

Essas permissões sustentam a página Usuários do painel, onde os escopos concedidos a cada membro são exibidos como chips:

A página Usuários: um card por usuário do painel com seu e-mail, permissões concedidas e controles de edição/desativação

Configurações operacionais

Permissão	Rotas HTTP	O que permite
`settings:read`	`GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve`	Visualizar configurações operacionais gerenciadas pelo painel e seus metadados; listar sobrescritas de janela de contexto por modelo; e resolver a janela efetiva para um modelo.
`settings:write`	`PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows`	Editar configurações operacionais e adicionar, alterar ou remover sobrescritas de janela de contexto por modelo. As alterações afetam novos eventos sem reiniciar o servidor.

Alertas e incidentes

Permissão	Rotas HTTP	O que permite
`alerts:read`	`GET /alerts`, `GET /alerts/:id`	Visualizar definições de alertas configurados.
`alerts:write`	`POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test`	Criar, editar, excluir e disparar testes de definições de alertas.
`incidents:read`	`GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers`	Visualizar incidentes e seu histórico de triagem.
`incidents:write`	`POST /alerts/:id/incidents`	Abrir um incidente manualmente contra um alerta existente.
`incidents:ack`	`POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe`	Reconhecer, atribuir, resolver e comentar em incidentes.

Auditorias

Permissão	Rotas HTTP	O que permite
`audits:read`	`GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid`	Visualizar definições de auditorias, histórico de execuções e descobertas.
`audits:write`	`POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status`	Criar, editar, excluir e executar auditorias; triar descobertas (reconhecer / silenciar / descartar / resolver / reabrir / atribuir).

Nota: Para conceder a uma chave acesso à superfície de auditorias, conceda audits:* explicitamente. Veja Notas de atualização e compatibilidade retroativa para saber como os detentores existentes foram migrados quando as Auditorias foram lançadas.

O endpoint seletor de destinatários GET /alerts/recipients (que lista os e-mails de membros que um editor de alertas pode notificar) é acessível por um detentor de either alerts:read or alerts:write, para que editores de alertas possam popular o seletor sem precisar de users:read.

Um visualizador de painéis precisa de ambos dashboards:read (para carregar as visualizações 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 painéis, e dashboards:delete para removê-los.

/health e /auth/* (requisição OTP, verificação OTP, verificação de sessão, logout) são sem autenticação por design; são o fluxo de login e a sonda de disponibilidade. GET /access-granters requer uma chave válida, mas nenhuma permissão específica, para que qualquer usuário conectado possa ver quais admins contatar sobre alterações de acesso.

Conjuntos de Permissões

Os conjuntos de permissões permitem aplicar um papel nomeado em vez de selecionar tokens individuais a cada vez. Em vez de selecionar uma dúzia de permissões uma a uma para cada novo usuário do painel ou chave de API, você escolhe um conjunto, e todos os atribuídos a ele carregam uma concessão consistente e revisável. Editar um conjunto personalizado reaaplica a nova concessão a todos os usuários já atribuídos a ele, portanto uma alteração de papel é uma única edição em vez de uma varredura por todos os membros. Cada organização é inicializada com três conjuntos embutidos:

Conjunto	Permissões	Destinado a
`read-only`	`events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read`	Acesso somente leitura em todas as superfícies operacionais.
`standard`	tudo em `read-only`, mais `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use`	Somente leitura mais as ações cotidianas de plantão: executar consultas, reavaliar sessões, reconhecer incidentes e usar o assistente de IA.
`admin`	toda permissão atribuível	Controle total da organização.

Os três conjuntos embutidos são imutáveis; seus nomes sempre significam a mesma coisa, portanto read-only, standard e admin são seguros para referenciar em políticas e onboarding. Um operador pode criar conjuntos personalizados adicionais para modelar papéis específicos da sua organização (por exemplo, um papel de “autor de painel” ou um papel de “somente coletor”). Os conjuntos são exibidos no painel e gerenciados pela API em GET /permission-sets (listar, protegido por users:read) e POST /permission-sets / PUT /permission-sets/:name / DELETE /permission-sets/:name (criar, editar, excluir um conjunto personalizado, protegido por settings:write). Excluir ou editar um conjunto embutido é recusado. A associação a conjuntos sustenta dois outros recursos:

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

Nota: Quando um conjunto inclui uma permissão que não é atribuível a chaves (por exemplo, um conjunto personalizado contendo keys:update), ao criar 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 painel não estão sujeitos a essa restrição.

Chave Admin de Bootstrap

A chave admin é a credencial raiz única que permite a um operador inicializar o acesso do zero: com ela você pode criar todas as outras chaves com escopo, convidar os primeiros usuários do painel e configurar a instância antes de qualquer outra chave existir. É a única chave que você não cria pela API de chaves; ela é provisionada a partir do ambiente para que o servidor seja acessível na primeira inicialização. Defina a variável de ambiente ADMIN_KEY no servidor. A cada inicialização, o servidor faz um upsert desse valor como uma chave admin com todas as permissões. Para rotacionar: altere ADMIN_KEY para um novo segredo e reinicie o servidor.

Escopo de organização

As organizações em si são criadas e gerenciadas fora de banda por um operador, não por esta API de chaves. O ciclo de vida de organizações e membros (criar / renomear / excluir / purgar uma organização; adicionar / atualizar / remover um membro) é feito com o CLI agenteye-orgctl; não há API HTTP ou botão no painel para isso. O que permanece inalterado: chaves de API por organização ainda são criadas no painel (ou via esta API de chaves) por membros da organização. Em uma implantação multi-organização, toda chave criada por um membro da organização (por esta API de chaves ou pela página Keys do painel) pertence a uma organização e só pode ler ou escrever os dados daquela organização; a organização é carimbada na chave na criação e aplicada em cada requisição. As duas chaves de bootstrap são a única exceção: a chave admin (originada do ADMIN_KEY) e a chave dashboard-assistant (originada do AGENT_API_KEY) têm escopo de instância (não carregam organização). O painel se autentica com a chave admin para poder fazer proxy de requisições por organização em nome dos membros conectados. Implantações de locatário único não precisam se preocupar com isso; todas as chaves pertencem à organização default embutida.

Criando Chaves

Use a chave admin (ou qualquer chave com permissão keys:create) para criar chaves com escopo adicionais.

Chave de coletor (somente ingestão)

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

Chave de painel (somente leitura)

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

Ao criar uma chave pela API HTTP, você fornece o valor de key você mesmo; escolha um segredo forte e armazene-o com segurança. (O painel funciona de forma diferente: ele gera um segredo forte para você e o exibe uma vez na criação; veja Gerenciamento de Chaves no Painel.) A resposta confirma que a chave foi criada:

{
  "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/keys \
  -H "Authorization: Bearer $ADMIN_KEY"

Os segredos das chaves não são retornados nas respostas de listagem, apenas IDs, nomes e permissões.

Desativando uma Chave

Desativar revoga o acesso imediatamente sem excluir o registro da chave.

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

Regenerando uma Chave

Gera um novo segredo para uma chave existente. O segredo antigo é invalidado imediatamente.

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

A resposta inclui o novo segredo em texto simples, exibido apenas uma vez.

Gerenciamento de Chaves no Painel

A página Keys no painel fornece uma interface para todas as operações acima. Você precisa de uma chave com permissão keys:read para visualizar a lista, e keys:create / keys:update / keys:disable / keys:regenerate para as ações de criar / editar / desativar / regenerar, respectivamente. Editar as permissões de uma chave (keys:update) é separado de criá-la (keys:create), portanto você pode conceder a um operador a capacidade de criar chaves sem a capacidade de reconfigurar as existentes, ou vice-versa. A chave admin cobre todas essas operações. Ao criar uma chave pelo painel, você não fornece o segredo; o painel gera um segredo forte para você e o exibe uma vez na criação. Copie-o imediatamente e armazene-o com segurança; ele nunca será exibido novamente, exatamente como em uma regeneração. Você ainda pode escolher as permissões da chave diretamente, ou inicializá-las a partir de um conjunto de permissões (veja abaixo).

A página Chaves de API: um card por chave mostrando seu nome, permissões concedidas e hora de criação, com ações de regenerar e desativar; chaves protegidas como admin são marcadas

Layout Recomendado de Chaves

Chave	Permissões	Usada por
`admin` (bootstrap via variável de ambiente `ADMIN_KEY`)	todas	Ops/configuração, e o painel (autentica com `ADMIN_KEY`, faz proxy de requisições de usuários com verificações de permissão)
Chave de coletor por host	`events:add`	Coletor em cada máquina de agente
`dashboard-assistant` (bootstrap via variável de ambiente `AGENT_API_KEY`)	`events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run`	Assistente de IA, inicializado automaticamente, protegido; não pode ser editado pela API
Chave de telemetria do assistente (opcional)	`events:add`	Auto-instrumentação do assistente de IA, se habilitada

Nota: 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 fixas no código-fonte para que o escopo não possa ser ampliado por má configuração: leitura de eventos / avaliações / painéis, mais gravação em painéis e leitura / escrita / execução de consultas para o fluxo de criação de “Pedir à IA para escrever uma consulta”. Todo SQL ainda passa pelo mesmo papel somente leitura e caminho SQL protegido de uma consulta escrita pelo usuário, portanto isso amplia a superfície de autoria, não a superfície de dados; operações destrutivas (queries:delete, dashboards:delete) são deliberadamente mantidas fora da chave do assistente. Como a chave admin, ela é protegida: não pode ser desativada ou regenerada pela API de chaves, apenas rotacionada alterando AGENT_API_KEY e reiniciando. Os usuários do painel adicionalmente precisam da permissão agent:use para ver e usar o assistente. Se você habilitar a auto-instrumentação, dê ao assistente uma chave separada somente com events:add.

Notas de atualização e compatibilidade retroativa

Você só precisa dessas informações se estiver atualizando uma instância existente; novas implantações podem ignorá-las.

Quando as Auditorias foram lançadas, os detentores existentes tiveram seus acessos ampliados seguindo os mesmos formatos de papel dos alertas: todo usuário e conjunto de permissões com alerts:read ganhou audits:read, e todo detentor de alerts:write ganhou audits:write. As chaves de API existentes não foram ampliadas. Conceda audits:* a uma chave explicitamente se ela precisar da superfície de auditorias.

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

Próximos passos

Python SDK: como o código do seu agente se autentica ao enviar eventos.
Segurança: como o login, controle de acesso e isolamento de dados por organização funcionam.

Overview

Features

SDK and CLI

Administration

Chaves de API

Os 3 tipos de chaves que a maioria das implantações precisa

Permissões

Ingestão e consulta de eventos

Sessões e avaliações

Painéis

Consultas salvas (compositor SQL)

Assistente de IA

Chaves de API

Usuários do painel

Configurações operacionais

Alertas e incidentes

Auditorias

Conjuntos de Permissões

Chave Admin de Bootstrap

Escopo de organização

Criando Chaves

Chave de coletor (somente ingestão)

Chave de painel (somente leitura)

Listando Chaves

Desativando uma Chave

Regenerando uma Chave

Gerenciamento de Chaves no Painel

Layout Recomendado de Chaves

Notas de atualização e compatibilidade retroativa

Próximos passos

​Os 3 tipos de chaves que a maioria das implantações precisa

​Permissões

​Ingestão e consulta de eventos

​Sessões e avaliações

​Painéis

​Consultas salvas (compositor SQL)

​Assistente de IA

​Chaves de API

​Usuários do painel

​Configurações operacionais

​Alertas e incidentes

​Auditorias

​Conjuntos de Permissões

​Chave Admin de Bootstrap

​Escopo de organização

​Criando Chaves

​Chave de coletor (somente ingestão)

​Chave de painel (somente leitura)

​Listando Chaves

​Desativando uma Chave

​Regenerando uma Chave

​Gerenciamento de Chaves no Painel

​Layout Recomendado de Chaves

​Notas de atualização e compatibilidade retroativa

​Próximos passos

Os 3 tipos de chaves que a maioria das implantações precisa

Permissões

Ingestão e consulta de eventos

Sessões e avaliações

Painéis

Consultas salvas (compositor SQL)

Assistente de IA

Chaves de API

Usuários do painel

Configurações operacionais

Alertas e incidentes

Auditorias

Conjuntos de Permissões

Chave Admin de Bootstrap

Escopo de organização

Criando Chaves

Chave de coletor (somente ingestão)

Chave de painel (somente leitura)

Listando Chaves

Desativando uma Chave

Regenerando uma Chave

Gerenciamento de Chaves no Painel

Layout Recomendado de Chaves

Notas de atualização e compatibilidade retroativa

Próximos passos