Documentazione

Panoramica API e OAuth

AnnexGroup mette a disposizione una REST API sotto /api/v1/.

Autenticazione

• Session-Cookie: per le richieste della web-UI
• OAuth 2.0: per applicazioni di terze parti
• API-Token / Access Token: per script, sistemi esterni e agenti IA

Gestire gli access token

In Impostazioni → Token di accesso possono essere creati token personali. Gli amministratori possono inoltre emettere in Amministrazione → Token di accesso amministrativi token di amministrazione del server con scope granulari.

Possibili scope amministrativi:

• admin – Pieno accesso amministrativo
• admin:read – API amministrativa in lettura
• admin:write – API amministrativa in scrittura
• admin:users, admin:agents, admin:domains, admin:queue, admin:security, admin:license, admin:backup, admin:settings, admin:mail

Gli access token sono particolarmente adatti a:

• Script di automazione (backup, monitoraggio, reporting)
• Amministrazione esterna tramite la REST API
• Agenti IA autorizzati a leggere o adattare configurazioni del server

API degli access token amministrativi

Esempio di creazione di un token:

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"Monitoring-Agent","scopes":["admin:read","admin:queue"],"expires_in_days":90}' \
     https://annexgroup.example/api/v1/admin/tokens

La risposta contiene il token in chiaro una sola volta:

{"token":"ag_...","expires_at":"2026-10-28T12:00:00Z"}

Admin-API

Tutte le funzioni amministrative sono accessibili anche tramite la REST API:

Registrare app OAuth

In Impostazioni → App OAuth gli utenti possono registrare applicazioni:

1. Indichi nome dell’app e redirect-URI
2. Riceva client-ID e client-secret
3. Assegni gli scope secondo il principio del privilegio minimo

Endpoint importanti

Le specifiche OpenAPI si trovano sotto:

• AnnexTalk Wire Protocol: docs/talk-protocol/v1/openapi.yaml
• Admin API: docs/openapi-admin.yaml

Integrazioni di esempio

Sotto examples/api-admin/ trova:

• annexgroup_admin.py — strumento Python dichiarativo per utenti, domini, alias e DKIM
• config.yaml — configurazione di esempio
• ansible/playbook.yml — playbook Ansible idempotente

Questi esempi sono un punto di partenza per flussi di lavoro Infrastructure-as-Code.