DE

Dokumentation

API- und OAuth-Übersicht

AnnexGroup stellt eine REST-API unter /api/v1/ bereit. Authentifizierung Session-Cookie: Für Web-UI-Anfragen OAuth 2.0: Für Drittanwendungen API-Token / Acces…

AnnexGroup stellt eine REST-API unter /api/v1/ bereit.

Authentifizierung

  • Session-Cookie: Für Web-UI-Anfragen
  • OAuth 2.0: Für Drittanwendungen
  • API-Token / Access Tokens: Für Skripte, externe Systeme und AI-Agents

Access Tokens verwalten

Unter Einstellungen → Access Tokens können persönliche Token erstellt werden. Administratoren können zusätzlich unter Administration → Admin-Access-Tokens Server-Admin-Tokens mit feingranularen Scopes ausstellen.

Mögliche Admin-Scopes:

  • admin – Voller Admin-Zugriff
  • admin:read – Admin-API lesend
  • admin:write – Admin-API schreibend
  • admin:users, admin:agents, admin:domains, admin:queue, admin:security, admin:license, admin:backup, admin:settings, admin:mail

Access Tokens eignen sich besonders für:

  • Automatisierungsskripte (Backup, Monitoring, Reporting)
  • Externe Administration über die REST-API
  • AI-Agents, die Server-Konfigurationen lesen oder anpassen dürfen

Admin-Access-Token API

Methode Endpunkt Beschreibung
GET /api/v1/admin/tokens Eigene Admin-Tokens auflisten
POST /api/v1/admin/tokens Neuen Admin-Token erstellen
DELETE /api/v1/admin/tokens/{id} Admin-Token widerrufen

Beispiel zum Erstellen eines Tokens:

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

Die Antwort enthält den Klartext-Token einmalig:

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

Admin-API

Alle administrativen Funktionen sind auch über die REST-API erreichbar:

Methode Endpunkt Beschreibung
GET /api/v1/admin/users Benutzer auflisten
POST /api/v1/admin/domains Domain anlegen
GET /api/v1/admin/queue Mail-Queue anzeigen
POST /api/v1/admin/security/preset Sicherheits-Preset anwenden

OAuth-Apps registrieren

Unter Einstellungen → OAuth-Apps können Benutzer Anwendungen registrieren:

  1. App-Name und Redirect-URI angeben
  2. Client-ID und Client-Secret erhalten
  3. Scopes gemäß Least-Privilege-Prinzip vergeben

Wichtige Endpunkte

Methode Endpunkt Beschreibung
GET /api/v1/mailboxes Postfächer auflisten
GET /api/v1/messages Mails abrufen
POST /api/v1/messages Mail senden
GET /api/v1/contacts Kontakte auflisten
GET /api/v1/events Termine abrufen

Die OpenAPI-Spezifikationen befinden sich unter:

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

Beispiel-Integrationen

Unter examples/api-admin/ findest du:

  • annexgroup_admin.py — deklaratives Python-Tool für Benutzer, Domains, Aliase und DKIM
  • config.yaml — Beispiel-Konfiguration
  • ansible/playbook.yml — idempotentes Ansible-Playbook

Diese Beispiele eignen sich als Ausgangspunkt für Infrastructure-as-Code-Workflows.

Etwas unklar oder falsch beschrieben? Sagen Sie uns Bescheid — wir korrigieren es. Ihre Frage zeigt uns, wo der Text nicht trägt.