Authentification
Comment vous authentifier avec une clé API, quels scopes existent et comment gérer vos clés en toute sécurité.
L'en-tête Authorization
Envoyez votre clé avec chaque requête sous forme de jeton Bearer :
GET /api/v1/me HTTP/1.1
Host: app.klantly.com
Authorization: Bearer kly_4fZ2mQ8v...Sans clé valide, vous obtenez 401 avec le code unauthenticated ou invalid_api_key.
À quoi ressemble une clé
Une clé commence toujours par kly_, suivi de 49 caractères. Le préfixe permet de reconnaître une clé divulguée, par exemple lors d'un secret scanning sur GitHub. Les derniers caractères forment une somme de contrôle : une clé contenant une faute de frappe est immédiatement refusée.
Klantly ne conserve qu'une empreinte irréversible de la clé. Personne ne peut l'afficher à nouveau, pas même Klantly. Vous l'avez perdue ? Créez-en une nouvelle.
Scopes
Une clé ne peut faire que ce que ses scopes autorisent. Lors de la création, choisissez Lecture seule, Accès complet ou votre propre sélection.
| Scope | Description |
|---|---|
customers.read | Lire les clients et les prospects |
customers.write | Créer et modifier les clients et les prospects |
deals.read | Lire les affaires et les étapes du pipeline |
deals.write | Créer, modifier, déplacer et archiver les affaires |
appointments.read | Lire les rendez-vous (avec le nom, l'e-mail et le téléphone du client), les types de rendez-vous et les disponibilités |
appointments.write | Créer, modifier, confirmer, annuler et terminer des rendez-vous (les automatisations de l'entreprise s'exécutent aussi) |
appointments.delete | Supprimer des rendez-vous |
appointments.send | Envoyer par e-mail les messages de rendez-vous aux clients |
tasks.read | Lire les tâches, les tableaux et les commentaires |
tasks.write | Créer, modifier, déplacer et terminer des tâches, et publier des commentaires |
tasks.delete | Supprimer des tâches |
work_orders.read | Lire les bons d'intervention, avec le nom, l'adresse et les coordonnées du client |
work_orders.write | Créer et modifier des bons d'intervention, et changer leur statut (terminer peut envoyer une demande d'avis) |
work_orders.delete | Supprimer des bons d'intervention |
services.read | Lire les demandes de service, avec le nom, l'adresse et les coordonnées du client |
services.write | Créer et modifier des demandes de service, changer leur statut et ajouter des photos |
services.delete | Supprimer des demandes de service |
quotes.read | Lire les devis, avec leurs lignes, leurs montants et les coordonnées du client |
quotes.write | Créer et modifier des devis (brouillons uniquement), et les accepter ou les refuser au nom du client |
quotes.delete | Supprimer des devis |
quotes.send | Envoyer les devis par e-mail aux clients |
invoices.read | Lire les factures, avec leurs lignes, leurs montants, les paiements et les coordonnées du client |
invoices.write | Créer des factures (aussi à partir d'un devis) et les modifier (brouillons uniquement), les annuler, enregistrer des paiements, les créditer et enregistrer un remboursement |
invoices.delete | Supprimer les factures brouillon |
invoices.send | Envoyer les factures par e-mail aux clients et obtenir le lien de paiement pour le client |
orders.read | Lire les commandes de la boutique, avec leurs lignes, leurs adresses et les coordonnées du client |
orders.write | Modifier le statut des commandes (le client reçoit alors un e-mail), renseigner le suivi de colis et ajouter des notes |
messages.read | Lire les conversations et les messages de la boîte de réception |
messages.send | Envoyer des messages aux clients et clôturer des conversations |
reviews.read | Lire les avis et les demandes d'avis |
reviews.write | Envoyer des demandes d'avis aux clients (créer un avis soi-même n'est pas possible) |
meta_copilot.read | Lire l'état et les alertes du copilote Meta |
meta_copilot.write | Arrêter le copilote Meta avec l'arrêt d'urgence, laisser agir ou écarter des opportunités et approuver ou rejeter des propositions (le mandat ne se configure que dans l'application) |
users.read | Lire les utilisateurs de l'entreprise |
company.read | Lire les données de l'entreprise |
webhooks.manage | Gérer les endpoints de webhook |
events.read | Récupérer les événements |
Une clé n'obtient jamais plus de droits que l'administrateur qui la crée, la modifie ou la renouvelle : vous ne pouvez pas accorder des droits que vous n'avez pas vous-même. S'il manque un scope, vous obtenez 403 avec le code insufficient_scope, et required_scope indique le scope nécessaire.
Un scope seul ne suffit parfois pas : si l'endpoint dépend d'une fonctionnalité absente du forfait de votre entreprise — par exemple le tableau de pipeline, les devis, les factures, les bons d'intervention, la boutique en ligne ou les avis — vous obtenez 403 avec le code feature_not_available, et le champ feature indique quelle fonctionnalité manque. Les scopes que votre entreprise ne peut pas utiliser ne peuvent pas non plus être accordés à une clé.
Date d'expiration, liste d'adresses IP et renouvellement
- Date d'expiration : 30, 90 ou 365 jours, ou illimitée. La valeur par défaut est de 365 jours. Dans Klantly, vous voyez quelles clés expirent bientôt.
- Liste d'adresses IP autorisées : limitez une clé aux adresses ou plages IP (CIDR) de votre serveur.
- Renouvellement : vous obtenez une nouvelle clé avec les mêmes réglages. L'ancienne peut rester valable 1 heure, 24 heures ou 7 jours, afin que votre intégration bascule sans interruption. Si la clé a été divulguée, ne choisissez aucun chevauchement : l'ancienne cesse alors aussitôt de fonctionner.
Si une clé a été divulguée
- Révoquez immédiatement la clé sous Intégrations → API. Elle cesse aussitôt de fonctionner.
- Créez une nouvelle clé et placez-la dans votre intégration.
- Consultez l'onglet Utilisation pour voir quelles requêtes ont été faites avec l'ancienne clé.
Conserver les clés en sécurité
- Conservez les clés dans une variable d'environnement ou un gestionnaire de secrets, jamais dans votre code source.
- N'utilisez une clé que sur un serveur. L'API n'accepte pas les requêtes provenant d'un navigateur (pas de CORS).
- Donnez à chaque intégration sa propre clé, avec uniquement les scopes nécessaires.
Dernière mise à jour le 18 septembre 2026