Api keys

​

title: “Chiavi API” description: “Documentazione delle chiavi API di AgentEye.”

​

Autorizzazioni

Non assegnabili alle chiavi. Due autorizzazioni valide sono solo per utenti/dashboard e non possono essere concesse a una chiave API: orgs:admin (amministrazione dell’istanza, esclusiva degli operatori) e keys:update. Una richiesta a POST /keys o PATCH /keys/:id che tenta di concedere una di queste viene rifiutata con HTTP 422. Vedi la riga keys:update di seguito per capire perché una chiave bearer può creare chiavi ma non modificarle.

​

Acquisizione e query di eventi

​

Sessioni e valutazioni

​

Dashboard

​

Query salvate (SQL composer)

​

Assistente AI

​

Chiavi API

​

Utenti del dashboard

​

Impostazioni operative

​

Avvisi e incidenti

​

Audit

Quando Audits è stato lanciato, i destinatari esistenti sono stati ampliati selon la stessa forma di ruoli degli avvisi: ogni utente e set di autorizzazioni che contiene alerts:read ha acquisito audits:read, e ogni detentore di alerts:write ha acquisito audits:write. Le chiavi API esistenti non sono state ampliate — concedi esplicitamente audits:* a una chiave se ha bisogno della superficie di audit.

I grant archiviati del token legacy alerts:ack vengono analizzati come incidents:ack quindi gli on-caller mantengono l’accesso senza ricreaere le chiavi. Il token non è più assegnabile dall’editor utenti del dashboard; la matrice offre incidents:ack invece.

L’endpoint del selettore destinatari GET /alerts/recipients (che elenca le email dei membri che un editor di avviso può notificare) è raggiungibile da un detentore di alerts:read o alerts:write, così gli editor di avviso possono popolare il selettore senza che gli venga concesso users:read.

Un visualizzatore di dashboard ha bisogno di entrambi dashboards:read (per caricare le visualizzazioni salvate) e evaluations:read (le metriche di salute vengono calcolate da dati di valutazione). Concedi dashboards:write per consentire a un utente di creare o modificare dashboard, e dashboards:delete per rimuoverli.

/health e /auth/* (richiesta OTP, verifica OTP, controllo sessione, logout) sono senza autenticazione per design; sono il flusso di login e la sonda di vivacità. GET /access-granters richiede una chiave valida ma nessuna autorizzazione specifica, quindi qualsiasi utente connesso può vedere quali admin contattare per le modifiche di accesso.

​

Set di autorizzazioni

• DEFAULT_USER_PERMISSIONS (il grant preselezionato quando un admin apre + nuovo utente) di default al set standard. Vedi Deployment.
• Il flag --set su agenteye-orgctl (gestione dei membri dell’operatore) inizia un membro da un set denominato, che poi ottimizzi con --add / --remove. Vedi Tenant Management.

Quando un set include un’autorizzazione che non è assegnabile alle chiavi (per esempio un set personalizzato che contiene keys:update), l’inizializzazione di una chiave da quel set scarta i token non assegnabili; il server altrimenti rifiuterebbe la chiave con HTTP 422. Gli utenti del dashboard non sono soggetti a questa restrizione.

​

Chiave Admin di Bootstrap

​

Ambito dell’organizzazione

​

Creazione di chiavi

​

Chiave collettore (solo acquisizione)

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"]
  }'

​

Chiave dashboard (sola lettura)

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"
}

​

Elenco delle chiavi

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

​

Disabilitazione di una chiave

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

​

Rigenerazione di una chiave

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

​

Key Management nel Dashboard

​

Layout di chiave consigliato

Chiave assistente. La chiave dell’assistente viene seminata automaticamente dal server dalla variabile di ambiente AGENT_API_KEY (lo stesso segreto che l’agente presenta come AGENTEYE_API_KEY); non c’è alcun passaggio manuale di creazione delle chiavi e nessuna chiave admin coinvolta. Le sue autorizzazioni sono fissate nel codice sorgente in modo che l’ambito non possa essere allargato da misconfiguration: lettura su eventi/valutazioni/dashboard, più scrittura del dashboard e lettura/scrittura/esecuzione delle query per il flusso di authoring “Chiedi all’AI di scrivere una query”. Tutto l’SQL passa comunque attraverso lo stesso ruolo di sola lettura e i controlli sql_guard di una query scritta dall’utente, quindi ciò allarga la superficie di authoring, non la superficie dati; le operazioni distruttive (queries:delete, dashboards:delete) rimangono deliberatamente fuori dalla chiave dell’assistente. Come la chiave admin, è protetta: non può essere disabilitata o rigenerata tramite l’API delle chiavi, solo ruotata cambiando AGENT_API_KEY e riavviando. Gli utenti del dashboard inoltre hanno bisogno dell’autorizzazione agent:use per vedere e utilizzare l’assistente. Se abiliti l’autostrumentazione, dai all’assistente una chiave separata events:add-only.