Jetons d'API et accès pour les développeurs

Mis à jour le 4 nov. 20267 min de lecture

Français

Sur cette page

Les jetons d'API permettent à du code ou à des scripts de communiquer avec votre compte Deskwoot sans utiliser de mot de passe. Vous en générez un par intégration (une synchronisation CRM, un tableau de bord sur mesure, un outil interne) et vous lui donnez uniquement les autorisations dont cette intégration a vraiment besoin. Vous pouvez révoquer un jeton à tout moment ; la révocation est immédiate et n'affecte aucun autre jeton. L'URL de base est https://api.deskwoot.com/v1/ et l'en-tête d'authentification est Authorization: Bearer YOUR_TOKEN. L'accès à l'API est réservé au forfait Enterprise ; les jetons déjà créés sur d'anciens forfaits continuent de fonctionner jusqu'à leur expiration.

Deskwoot propose une API REST qui vous donne un accès par programmation à vos données et à vos workflows de support. Que vous créiez des intégrations sur mesure, synchronisiez les données des tickets avec vos outils internes ou automatisiez des tâches répétitives, les jetons d'API vous permettent de vous authentifier en toute sécurité sans partager vos identifiants de connexion. Ce guide vous explique comment générer des jetons, faire votre premier appel à l'API et suivre les bonnes pratiques qui protègent votre compte.

L'API REST est une fonctionnalité Enterprise. L'essai Enterprise de 7 jours, par lequel commence chaque nouveau compte, n'inclut pas les jetons d'API ; il vous faut un forfait Enterprise actif pour les créer et les utiliser. Si vous êtes sur un forfait inférieur et avez besoin de l'accès à l'API, vous devrez passer au forfait Enterprise. Pour une vue plus complète de ce que couvre l'API, consultez la présentation de l'API REST.

Comment générer un jeton d'API ?

Connectez-vous à votre compte Deskwoot et allez dans Paramètres > Jetons d'API.
Cliquez sur Créer un jeton. Seuls les administrateurs peuvent créer des jetons.
Donnez au jeton un nom parlant (par exemple Synchro CRM, production) pour retrouver plus tard à quoi il sert.
Sélectionnez les autorisations précises que le jeton doit avoir. N'accordez que les niveaux d'accès dont votre intégration a vraiment besoin. Vous pouvez aussi choisir une date d'expiration.
Confirmez et copiez le jeton tout de suite. Pour des raisons de sécurité, le jeton complet ne s'affiche qu'une seule fois.

Comment utiliser l'API ?

Toutes les requêtes à l'API se font sur l'URL de base suivante :

https://api.deskwoot.com/v1/

Ajoutez votre jeton d'API dans l'en-tête Authorization de chaque requête :

Authorization: Bearer YOUR_TOKEN

Exemple de requête

Un simple appel cURL pour tester votre connexion peut ressembler à ceci :

curl -H "Authorization: Bearer YOUR_TOKEN" https://api.deskwoot.com/v1/me

Si le jeton est valide, l'API renvoie l'ID de votre compte et les autorisations du jeton. Sinon, vous recevez une erreur d'authentification. La référence complète des endpoints se trouve dans la documentation de l'API.

Quelles sont les bonnes pratiques ?

Accordez le moins d'accès possible. Donnez à chaque jeton uniquement les autorisations dont il a besoin. Évitez de créer des jetons avec un accès administrateur complet, sauf si vous en avez vraiment besoin.
Renouvelez les jetons régulièrement. Révoquez de temps en temps les anciens jetons et générez-en de nouveaux, surtout quand des membres de l'équipe changent de rôle ou partent.
Stockez les jetons en lieu sûr. Gardez-les dans des variables d'environnement ou un gestionnaire de secrets. Ne les écrivez jamais en dur dans du code côté client et ne les ajoutez jamais à votre système de gestion de versions.
Utilisez des noms parlants. Nommer chaque jeton d'après l'intégration ou l'environnement qu'il sert facilite les vérifications.
Surveillez l'utilisation. Passez régulièrement en revue vos jetons actifs dans Paramètres > Jetons d'API et supprimez ceux qui ne servent plus.

Comment résoudre les erreurs de jeton ?

401 Unauthorized : Vérifiez que le jeton a été copié correctement, qu'il n'a pas été révoqué et qu'il figure dans l'en-tête avec le préfixe Bearer.
403 Forbidden : Le jeton n'a peut-être pas les autorisations pour l'endpoint que vous appelez. Créez un nouveau jeton avec les bonnes autorisations et révoquez l'ancien. Une erreur 403 apparaît aussi quand l'espace de travail n'est plus sur le forfait Enterprise.
Limite de requêtes : Si vous recevez des erreurs de limite de requêtes, appelez l'API moins souvent ou ajoutez à votre code de nouvelles tentatives avec un délai exponentiel.

Questions fréquentes

Et si je préfère qu'un agent IA utilise le helpdesk ?

Si vous voulez qu'un agent IA externe utilise Deskwoot plutôt que de créer votre propre intégration, regardez le serveur MCP. C'est aussi une fonctionnalité Enterprise, et il utilise des jetons de bot aux autorisations limitées.

Où créer un jeton d'API ?

Paramètres → Jetons d'API → Créer un jeton. Choisissez un nom parlant, sélectionnez les autorisations et copiez le jeton dès qu'il s'affiche. Pour des raisons de sécurité, le jeton ne s'affiche qu'une seule fois. De notre côté, nous ne stockons qu'un hachage SHA-256, jamais le jeton lui-même.

Quelles autorisations sont disponibles ?

Dans Paramètres → Jetons d'API, vous pouvez choisir read (tout), write (tout), les paires plus restreintes contacts:read, contacts:write, conversations:read, conversations:write, help_center:read, help_center:write, et inbound:ingest (pour envoyer des messages dans une boîte de réception de canal API REST, non couvert par write). Choisissez la plus restreinte dont l'intégration a vraiment besoin.

Que se passe-t-il si je perds un jeton ?

Révoquez-le et créez-en un nouveau. Il n'y a aucun moyen de le récupérer ; de notre côté non plus, la valeur du jeton n'est pas stockée sous une forme récupérable, et c'est voulu.

Quels forfaits donnent accès à l'API ?

Enterprise. Les jetons créés sur d'anciens forfaits avant le changement de tarifs de 2026-05 continuent de fonctionner jusqu'à leur expiration (l'indicateur legacyApiAccess dans l'enregistrement du jeton les laisse passer), mais les nouveaux jetons nécessitent Enterprise. L'essai de 7 jours n'inclut pas les jetons d'API.

Puis-je limiter un jeton à une seule boîte de réception ou à une seule équipe ?

Pas au niveau des autorisations. Solution de contournement : filtrez de votre côté chaque requête sur les ID de cette boîte de réception ou de cette équipe.

Les jetons sont-ils liés à un utilisateur ou à un compte ?

Aux deux : un jeton est lié à un utilisateur dans un compte. Les actions du jeton sont attribuées à l'utilisateur qui l'a créé. Chaque membre ne voit et ne révoque que ses propres jetons, et retirer quelqu'un de l'espace de travail ne révoque pas ses jetons : demandez-lui donc de les révoquer avant son départ. Bonne pratique pour les intégrations partagées : confiez les jetons d'intégration à un utilisateur dédié, un compte de service « API ».

Comment renouveler les jetons en toute sécurité, sans interruption ?

Créez le nouveau jeton, déployez-le partout, laissez l'ancien actif pendant un cycle de déploiement, puis révoquez-le. Les deux jetons fonctionnent en parallèle pendant ce temps, donc rien ne casse.

L'API compte-t-elle dans mon quota de conversations IA ?

Non. Lire des conversations, publier des réponses d'agents ou gérer des contacts via l'API n'utilise pas de conversations IA. Les conversations IA sont utilisées quand Fynn ou Copilot travaille sur une conversation, ou quand un message vocal de cette conversation est transcrit.

Puis-je utiliser l'API depuis le navigateur ?

Techniquement oui, mais ne mettez pas de jetons dans du code côté client : toute personne qui consulte le code source peut les voler. Les appels depuis le navigateur doivent passer par votre propre backend, qui garde le jeton.

Puis-je définir une date d'expiration pour un jeton ?

Oui. Choisissez une date sous Expiration (facultatif) lors de la création du jeton ; le jeton fonctionne jusqu'à la fin de ce jour dans votre fuseau horaire, puis il est refusé à chaque appel. Pratique pour les intégrations de courte durée (un audit, un script de migration ponctuel) : vous n'avez pas à penser à faire le ménage.

Puis-je recevoir des webhooks au lieu d'interroger l'API en boucle ?

Oui. Paramètres → Webhooks → abonnez-vous à des événements (nouvelle conversation, nouveau message, changement de statut, etc.). Chaque envoi est signé avec HMAC (en-tête X-Deskwoot-Signature) ; vérifiez la signature avant de le traiter.

L'API REST est-elle disponible sur tous les forfaits ?

Non. L'API REST est une fonctionnalité Enterprise. Les forfaits payants inférieurs ne l'incluent pas, pas plus que l'essai Enterprise de 7 jours : les jetons d'API nécessitent un forfait Enterprise actif.

Puis-je créer plusieurs jetons d'API ?

Oui. Vous pouvez générer autant de jetons que nécessaire. Nous recommandons un jeton distinct pour chaque intégration ou environnement, pour pouvoir en révoquer un sans toucher aux autres.

Que se passe-t-il si mon jeton est compromis ?

Allez immédiatement dans Paramètres > Jetons d'API, révoquez le jeton compromis et générez-en un nouveau. Mettez ensuite à jour tous les services qui utilisaient l'ancien jeton.

Où créer un jeton ?

Dans Paramètres > Jetons d'API. Nommez le jeton, accordez-lui uniquement les autorisations nécessaires et copiez-le tout de suite, car la valeur complète ne s'affiche qu'une seule fois.

Ce guide vous a-t-il aidé ?

Continuer la lecture

Demander à Fynn à propos de ce guide

Obtenez une réponse courte tirée de ce guide et du reste du centre d'aide.