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 par entreprise par défaut ; configurable par entreprise dans les réglages de l’addon (`max_active_keys`). La valeur en vigueur est visible dans le dashboard.
Expiration	Optionnelle à la création (90 / 180 / 365 jours ou sans expiration). Si l’entreprise a fixé `default_expiration_days` et que vous ne demandez pas d’expiration explicite, la clé expire quand même selon cette politique.

Vérifiez expires_at dans la réponse de création. C’est la seule source fiable : même sans expiration demandée, la politique default_expiration_days de votre entreprise a pu en poser une. Notez-la et planifiez la rotation.

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.

Désactiver l’addon Public API révoque TOUTES les clés API de l’entreprise (motif addon_disabled) et supprime l’entreprise sandbox avec ses données. Le réactiver ne les ressuscite pas : il faut émettre de nouvelles clés. Voir le cycle de vie.

Rotation

Une rotation atomique existe : un clic dans le dashboard Kinmu (Développeurs → API keys) émet la clé de remplacement en conservant les scopes, le nom, l’environnement et la politique d’expiration, et révoque l’ancienne dans la même transaction. Vous récupérez le nouveau secret une seule fois, comme à la création. L’API /v1 n’expose pas la gestion des clés : création, rotation et révocation se font toujours depuis le dashboard.

Une clé déjà révoquée ne peut pas être tournée : pour la remplacer, créez-en une nouvelle.

Si vous préférez faire se chevaucher les deux clés pour déployer sans interruption, procédez à la main :

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.

Révoquer des clés et des webhooks (DELETE) fonctionne même avec un abonnement inactif : c’est un contrôle de sécurité, pas de la consommation de service. Vous n’êtes jamais privé du moyen de couper une credential compromise.

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`	Entreprise suspendue ou archivée, sans abonnement, abonnement suspendu, essai expiré, ou abonnement résilié et arrivé à terme ou expiré. Toujours 403, jamais 402.
403	`addon_disabled`	L’addon Public API n’est pas actif.

Le format complet des erreurs est décrit dans Conventions → Erreurs.