Utiliser l'API REST de Xcellerate OPS avec des clés API personnelles

Xcellerate OPS dispose d'une API REST documentée (v1). Elle vous permet de connecter vos propres outils, scripts ou plateformes d'automatisation aux tickets, entreprises, contacts, deals, projets, temps enregistrés, assets et plus encore. Chaque utilisateur crée ses propres clés API depuis son profil, et une clé peut faire exactement ce que cet utilisateur peut faire dans l'application, rien de plus. Ce guide s'adresse aux administrateurs techniques de MSP et de PME de services.

TL;DR

• Créez une clé dans votre profil, section API keys, et copiez le jeton tout de suite : il n'est affiché qu'une fois.
• Envoyez deux en-têtes à chaque requête : Authorization: Bearer <token> et X-Tenant-Id.
• Une clé hérite des droits de votre utilisateur. Par défaut, 120 requêtes par minute et par clé.

Avant de commencer

• Tout membre du personnel peut créer des clés pour lui-même. Aucun rôle admin n'est nécessaire.
• Ce qu'une clé peut faire suit exactement vos droits d'équipe. Ce qui est bloqué dans l'application l'est aussi dans l'API.
• Vous disposez d'un client HTTP capable d'envoyer des en-têtes : un script, une plateforme d'automatisation ou votre propre application.
• Vous pouvez avoir au maximum 20 clés actives par utilisateur.

À noter : la section des clés API n'existe qu'en anglais dans l'application. Les libellés ci-dessous sont donc en anglais.

Créer et utiliser une clé API

Étape 1 : ouvrir vos clés API

Allez dans votre profil et ouvrez la section API keys.

Étape 2 : créer la clé

Donnez à la clé un nom qui indique son usage. Choisissez si elle peut seulement lire ou aussi écrire, et fixez si besoin une date d'expiration dans le futur. Les clés sont en lecture seule, sauf si vous les créez avec un accès en écriture. Si vous avez seulement besoin de lire des données, restez en lecture seule.

Étape 3 : copier le jeton

Après la création, OPS affiche le message « Copy your new API key now — it will not be shown again. » Copiez le jeton immédiatement et conservez-le en lieu sûr. Les jetons commencent par xok_. Si vous le perdez, créez une nouvelle clé.

Étape 4 : copier l'identifiant de votre espace de travail

La même section affiche l'identifiant de votre espace de travail. Copiez-le avec le bouton Copy. Il est nécessaire pour chaque requête.

Étape 5 : faire une première requête

Testez votre clé avec une requête simple vers /api/v1/me, avec les deux en-têtes :

GET /api/v1/me
Authorization: Bearer <token>
X-Tenant-Id: <workspace id>

Le lien API documentation ↗ de la section ouvre la documentation interactive. Vérifiez-y l'adresse de base correcte et les endpoints disponibles.

Étape 6 : révoquer les clés inutilisées

Vous révoquez une clé depuis la même liste. Pour chaque clé, vous voyez sa dernière utilisation, ce qui aide à repérer celles dont plus personne n'a besoin.

Ce qui se passe après la connexion

• Format : JSON pour les requêtes et les réponses. Les listes sont paginées par curseur.
• Couverture : notamment entreprises, contacts, interactions CRM, champs personnalisés, tickets et planifications de tickets, projets avec planning et finances, temps enregistrés, notes de frais, absences, temps de travail, assets et CMDB, logiciels, services, changes, problems, incidents majeurs, releases, base de connaissances, opportunités, grilles tarifaires, factures récurrentes, rapports, rapports SLA et XLA, appels et enregistrements, et journal des actions IA. La liste complète figure dans la documentation de l'API.
• Portail client : les clients qui utilisent votre portail client peuvent y créer leurs propres clés, limitées à leurs propres données.

Pour savoir comment OPS protège les accès, consultez sécurité et contrôle d'accès. Toutes les connexions sont présentées dans intégrations européennes et sécurité.

Bon à savoir

• Limite : par défaut 120 requêtes par minute et par clé. RMM Labs peut l'augmenter pour un espace de travail sur demande. Chaque réponse contient les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining.
• Échecs d'authentification : des échecs répétés depuis la même adresse sont temporairement bloqués.
• Les clés appartiennent à une personne. Désactiver un utilisateur révoque ses clés et le bloque. Les intégrations qui tournent sur ces clés s'arrêtent alors. Anticipez-le lors du départ d'un collaborateur.
• Les préférences personnelles, comme celles de la synchronisation d'agenda, ne sont pas accessibles via l'API.

Dépannage

• 401 unauthenticated « Invalid API credentials. » Jeton erroné, expiré ou révoqué, X-Tenant-Id manquant ou incorrect, espace de travail suspendu ou utilisateur désactivé. Tous ces cas donnent volontairement la même réponse.
• 429 rate_limited « Too many requests. » Attendez le nombre de secondes indiqué dans l'en-tête Retry-After.
• 429 « Too many failed authentication attempts. » Votre adresse IP est temporairement bloquée après trop d'échecs.
• « You have reached the maximum number of API keys. » Vous avez 20 clés actives. Révoquez-en une d'abord.

Pour commencer

Vous voulez connecter OPS à vos propres scripts et outils ? Commencez gratuitement et créez votre première clé API dans votre profil.