SMSEagle offre une puissante API REST intégrée. L’API est dédiée à l’intégration de SMSEagle avec n’importe quel système externe ou application.

Référence API

SMSEagle offre deux versions d’API :

  • API v2 - recommandée, à utiliser pour chaque nouvelle intégration. Une API RESTful moderne basée sur la spécification OpenAPI 3.0. Référence API v2

  • API v1 - l’API héritée, conservée uniquement pour la compatibilité descendante. Une API HTTP et JSON-RPC simple. Elle fonctionne toujours et est toujours supportée, mais elle ne reçoit pas de nouvelles fonctionnalités - ne développez pas de nouvelles intégrations contre elle. Référence API v1

En raison du contenu étendu de la documentation API, elle est maintenue comme un document séparé. Suivez les liens ci-dessus pour la spécification complète de chaque API.

Clés API

Une intégration s’authentifie avec une clé API au lieu d’un mot de passe utilisateur. Les clés sont conservées séparément pour chaque version d’API, sur deux pages :

  • Settings > API > API v2 (/settings/api/v2)

  • Settings > API > API v1 (/settings/api/v1)

Une clé appartient toujours à un utilisateur et agit en tant que cet utilisateur, elle voit donc les messages et contacts de cet utilisateur. Les permissions sont accordées par clé, ce qui vous permet de limiter un système de monitoring à la lecture tandis qu’un formulaire web ne peut que envoyer.

Clés API v2

Ceci est la page à utiliser pour une nouvelle intégration.

Page des clés API v2 listant chaque clé avec son propriétaire, permissions et dernière utilisation (valeurs d'exemple)

Clés API v2

Clés API v1

API v1 est l’API héritée. Créez une clé v1 uniquement pour une intégration existante qui ne peut pas être déplacée vers v2 - pour toute nouvelle création, créez plutôt une clé API v2.

Page des clés API v1 listant chaque clé avec son propriétaire, permissions et dernière utilisation (valeurs d'exemple)

Clés API v1

Création d’une clé

Create API key ouvre le formulaire de la version API dont vous êtes sur la page :

Champ

Ce qu’il fait

Key name

Comment vous reconnaîtrez cette intégration plus tard, par exemple Zabbix ou Website form.

Owner

L’utilisateur en tant lequel la clé agit. La clé voit les messages et contacts de cet utilisateur.

Key enabled

Une clé désactivée est refusée par l’API sans être supprimée, ce qui désactive une intégration sans perdre sa configuration.

Access to all users” resources

API v2 uniquement. Permet à la clé de lire et modifier les ressources détenues par d’autres utilisateurs (voir ci-dessous).

Permissions

Seules les méthodes que vous activez peuvent être appelées avec cette clé.

La clé elle-même s’affiche une fois, immédiatement après sa création. Copiez-la alors et conservez-la en lieu sûr. Si vous la perdez, révoquez cette clé et créez-en une nouvelle - les autres clés du même utilisateur continuent de fonctionner.

Quels utilisateurs ont accès à l’API

System > Users affiche, par utilisateur, le nombre de clés API de l’utilisateur et pour quelle version de l’API. Le badge renvoie directement à la page des clés correspondantes.

Colonne d'accès API dans la liste Users, affichant le nombre de clés par utilisateur

Accès à l’API, affiché par utilisateur dans la liste Users

Accès aux ressources d’autres utilisateurs

Les deux versions de l’API diffèrent dans la largeur d’accès d’une clé API aux données d’autres utilisateurs :

  • En API v1, une clé a accès par défaut aux ressources de tous les autres utilisateurs - contacts du carnet d’adresses, groupes, etc.

  • En API v2, l’accès est plus granulaire : une clé a accès par défaut uniquement aux ressources qu’elle a créées elle-même. Pour autoriser l’accès aux ressources de tous les autres utilisateurs, activez Access to all users” resources sur la clé.