Documentation

Vue d'ensemble de l'API et d'OAuth

AnnexGroup fournit une API REST sous /api/v1/.

Authentification

• Cookie de session : pour les requêtes de l'interface web
• OAuth 2.0 : pour les applications tierces
• Jetons d'accès / access tokens : pour les scripts, les systèmes externes et les agents d'IA

Gestion des jetons d'accès

Sous Réglages → Jetons d'accès, vous pouvez créer des jetons personnels. Les administrateurs peuvent en plus émettre sous Administration → Jetons d'accès admin des jetons d'administration serveur avec des portées (scopes) fines.

Portées administrateur possibles :

• admin – accès administrateur complet
• admin:read – API d'administration en lecture
• admin:write – API d'administration en écriture
• admin:users, admin:agents, admin:domains, admin:queue, admin:security, admin:license, admin:backup, admin:settings, admin:mail

Les jetons d'accès conviennent particulièrement pour :

• les scripts d'automatisation (sauvegarde, supervision, rapports)
• l'administration externe via l'API REST
• les agents d'IA autorisés à lire ou modifier des configurations du serveur

API des jetons d'accès admin

Exemple de création d'un jeton :

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 réponse contient le jeton en clair une seule fois :

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

API d'administration

Toutes les fonctions administratives sont également accessibles via l'API REST :

Enregistrer des applications OAuth

Sous Réglages → Applications OAuth, les utilisateurs peuvent enregistrer des applications :

1. Indiquez le nom de l'application et l'URI de redirection
2. Recevez l'ID client et le secret client
3. Attribuez des scopes selon le principe du moindre privilège

Points d'API importants

Les spécifications OpenAPI se trouvent sous :

• Protocole AnnexTalk Wire : docs/talk-protocol/v1/openapi.yaml
• API d'administration : docs/openapi-admin.yaml

Exemples d'intégration

Sous examples/api-admin/, vous trouvez :

• annexgroup_admin.py — outil Python déclaratif pour les utilisateurs, domaines, alias et DKIM
• config.yaml — configuration d'exemple
• ansible/playbook.yml — playbook Ansible idempotent

Ces exemples servent de point de départ pour des flux d'infrastructure-as-code.