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 chiffrée 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 |
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.
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 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 15 septembre 2026