Authentification et clés d’API
L’API utilise des clés d’API d’entreprise (des comptes de service, non liés à un utilisateur). Chaque requête s’authentifie avec la clé en Bearer token :
curl https://api.kinmu.app/v1/organization \
-H "Authorization: Bearer kinmu_sk_live_xxxxxxxx"Nature des clés
L’entreprise est toujours résolue à partir de la clé : vous n’envoyez jamais de companyId dans l’URL ni dans le body.
| Aspect | Détail |
|---|---|
| Format | kinmu_sk_live_<40+ chars> (production) · kinmu_sk_test_<40+ chars> (sandbox). |
| Visibilité | Les clés ne sont affichées qu’une seule fois, à la création. Ensuite, seuls le préfixe et les premiers caractères restent visibles. |
| Émission | Depuis le dashboard my.kinmu.app → Développeurs (réservé à global_admin / company_manager). |
| Limite | 10 clés actives maximum par entreprise. |
| Expiration | Optionnelle (90 / 180 / 365 jours ou sans expiration). |
Scopes
Chaque clé porte des scopes explicites (moindre privilège). Sans le scope requis, l’endpoint répond 403 invalid_scope.
| Scope | Permet |
|---|---|
org:empleados:read | Lire les salariés. |
org:empleados:write | Créer, mettre à jour et gérer le départ des salariés. |
org:fichajes:read | Lire les pointages et les work-summaries. |
org:fichajes:write | Enregistrer des pointages. |
org:ausencias:read | Lire les absences. |
org:ausencias:write | Créer, approuver et refuser des absences. |
org:saldos:read | Lire les soldes de congés. |
org:estructura:read | Lire les locations et les units. |
org:informes:read | Demander et télécharger des rapports. |
webhooks:manage | Gérer les webhooks sortants. |
GET /v1/organization ne requiert aucun scope particulier : il sert à l’introspection et à la validation de la clé. Les rapports exigent en plus le scope de lecture de leur domaine : p. ex. absences_export requiert org:ausencias:read.
N’accordez à chaque intégration que les scopes dont elle a besoin.
Sandbox
Les clés kinmu_sk_test_ opèrent toujours sur une entreprise sandbox avec des données synthétiques, isolée de vos données réelles. Voir le guide Sandbox.
Rotation
Faire tourner une clé revient à en créer une nouvelle et révoquer l’ancienne. Flux sans interruption de service :
- Créez la nouvelle clé avec les mêmes scopes.
- Déployez votre intégration avec la nouvelle clé.
- Vérifiez qu’elle fonctionne (p. ex. un
GET /v1/organization). - Révoquez l’ancienne clé.
Révocation
La révocation est immédiate depuis le dashboard : la clé cesse de fonctionner dès la requête suivante (401 unauthenticated). Révoquez sans attendre toute clé que vous soupçonnez compromise et vérifiez son last_used_ip.
Bonnes pratiques
- Ne publiez jamais une clé dans du code client, une app mobile, un dépôt ou des logs. Ce sont des identifiants de serveur.
- Stockez-les dans un gestionnaire de secrets ou des variables d’environnement.
- Utilisez une clé par intégration pour pouvoir révoquer de façon granulaire.
- Appliquez le moindre privilège : uniquement les scopes indispensables.
- Configurez une expiration et effectuez des rotations régulières.
- Dans vos logs, n’enregistrez jamais le header
Authorization.
Erreurs d’authentification
| HTTP | code | Cause |
|---|---|---|
| 401 | unauthenticated | Clé absente, invalide, révoquée ou expirée. |
| 403 | invalid_scope | La clé n’a pas le scope requis (errors.required_scope). |
| 403 | subscription_inactive | L’abonnement de l’entreprise est suspendu. |
| 403 | addon_disabled | L’addon Public API n’est pas actif. |
Le format complet des erreurs est décrit dans Conventions → Erreurs.