Créer une clé API

Avec une clé API, votre propre logiciel travaille avec les données de vos sites, par exemple pour publier vos offres d'emploi depuis votre logiciel RH. Une clé est un mot de passe pour logiciel, avec les droits que vous choisissez. Un assistant IA n'en a pas besoin : il se connecte via le MCP, avec votre compte. Voir Modifier votre site avec votre assistant IA.

Avant de commencer

• Qui : le propriétaire ou un administrateur de l'organisation. Un rédacteur, un designer ou un membre ne voit pas les clés API.

• Formule : toutes les formules.

• Il vous faut : savoir quelle intégration recevra la clé et ce qu'elle doit pouvoir faire, et un endroit sûr pour la conserver, comme un gestionnaire de mots de passe.

Créer une clé

1. Connectez-vous à app.kintsu.be et allez dans Organisation › Paramètres › Clés API.

2. Sous Nom, indiquez à quoi sert la clé, par exemple « Lien comptabilité ». Vous saurez ainsi plus tard ce qui l'utilise.

3. Sous Droits, cochez uniquement ce dont l'intégration a besoin. Voir plus bas.

4. Sous Valable, choisissez une durée : 30 jours, 90 jours (par défaut), 365 jours ou Sans date de fin. Préférez 90 ou 365 jours.

5. Cliquez sur Créer la clé. Si vous vous êtes connecté il y a un moment, Kintsu vous demande d'abord votre mot de passe dans Confirmez que c'est vous.

6. Vous voyez : « Copiez la clé maintenant : elle n'est affichée qu'une seule fois. » Cliquez sur Copier.

7. Conservez immédiatement la clé en lieu sûr.

Attention : Kintsu ne conserve pas la clé elle-même, seulement une empreinte irréversible. Personne ne peut donc la réafficher. Vous l'avez perdue ? Créez-en une nouvelle et supprimez l'ancienne.

Quels droits choisir ?

Vous ne voyez que les droits de votre propre rôle : une clé n'en reçoit jamais plus que vous. L'API en utilise quatre :

• site.read : lire vos sites, vos tables et leurs éléments.

• content.edit : créer, modifier et mettre à la corbeille des éléments, y compris plusieurs à la fois avec votre propre identifiant, et téléverser des fichiers.

• content.publish : mettre les brouillons en ligne.

• submission.read : lire les envois de vos formulaires.

L'API n'utilise pas encore les autres droits de la liste, comme domain.manage. Laissez-les décochés. Choisissez toujours le minimum : une intégration qui affiche seulement vos offres d'emploi n'a besoin que de site.read.

Tester la clé

Mettez la clé dans une variable d'environnement et demandez à Kintsu pour qui elle travaille. Sur macOS ou Linux, dans le terminal :

export KINTSU_API_KEY="collez-ici-votre-cle"

curl https://app.kintsu.be/api/v1/whoami -H "Authorization: Bearer $KINTSU_API_KEY"

Sur Windows, dans PowerShell :

$env:KINTSU_API_KEY = "collez-ici-votre-cle"

curl.exe https://app.kintsu.be/api/v1/whoami -H "Authorization: Bearer $env:KINTSU_API_KEY"

La réponse indique votre organisation, le nom de la clé et ses droits, par exemple :

{"organization": {"id": "…", "name": "Bakkerij Peeters", "slug": "bakkerij-peeters"}, "key": {"id": "…", "name": "Lien comptabilité"}, "permissions": {"site": ["read"]}}

Vous recevez une erreur ? Voir Ça ne marche pas ? plus bas.

Conserver et partager en sécurité

• Conservez la clé dans un gestionnaire de mots de passe, ou dans les secrets de votre serveur (une variable d'environnement ou un coffre-fort). Jamais dans le code d'un site ou d'une application, et jamais dans Git.

• Utilisez-la uniquement sur un serveur, jamais dans un navigateur ou une application mobile : n'importe qui pourrait la lire.

• Ne l'envoyez jamais par e-mail, par chat ou en capture d'écran. Transmettez-la à un développeur via un gestionnaire de mots de passe ou un lien à usage unique.

• Créez une clé par intégration ou par développeur. Vous pouvez alors en retirer une sans déranger les autres.

Quand une clé cesse-t-elle de fonctionner ?

Une clé agit pour la personne qui l'a créée, avec au plus les droits que cette personne a à ce moment-là. Elle cesse immédiatement de fonctionner si :

• sa durée est écoulée (la liste affiche alors Expirée) ;

• quelqu'un la supprime ;

• la personne qui l'a créée quitte l'organisation ou en est retirée ;

• le rôle de cette personne exige la vérification en deux étapes et celle-ci est désactivée.

Si la personne reçoit un rôle moins élevé, la clé perd les droits que ce rôle n'a pas. Pour une intégration durable, créez donc la clé avec un compte qui reste, comme celui du gérant.

Vérifier

Sous Clés de l'organisation, vous voyez pour chaque clé son nom, le début de la clé, ses droits, qui l'a créée et quand, jusqu'à quand elle est valable et quand elle a été utilisée pour la dernière fois. Supprimez celles que vous n'utilisez plus. Une organisation peut avoir au plus 50 clés.

Renouveler sans interruption

Il n'y a pas de bouton pour renouveler une clé. Procédez ainsi, bien avant l'expiration de l'ancienne :

1. Créez une nouvelle clé avec les mêmes droits.

2. Mettez la nouvelle clé dans votre intégration.

3. Testez avec whoami et vérifiez que votre intégration fonctionne. Dans la liste, la nouvelle clé indique quand elle a été utilisée pour la dernière fois.

4. Supprimez l'ancienne clé.

Retirer une clé

Cliquez sur Supprimer à côté de la clé. Elle cesse immédiatement de fonctionner : tout logiciel qui l'utilise reçoit désormais une erreur 401.

La clé a fuité ?

La clé s'est retrouvée dans un e-mail, un chat, une capture d'écran ou du code sur GitHub ?

1. Supprimez-la immédiatement, même si vous n'êtes pas sûr que quelqu'un l'a vue.

2. Créez une nouvelle clé et mettez-la dans votre intégration.

3. Vérifiez ce qui s'est passé : dans Organisation › Paramètres › Journal d'audit, et dans l'Historique de l'éditeur. Les modifications faites avec une clé y figurent avec « via l'API ».

4. Annulez ce qui ne va pas, ou rétablissez une publication précédente. Voir Publier et annuler.

Ça ne marche pas ?

• 401 avec le code API_KEY_INVALID : la clé est absente, erronée, expirée ou supprimée, ou la personne qui l'a créée n'est plus membre. Vérifiez aussi que l'en-tête est exactement Authorization: Bearer, suivi de la clé.

• 403 avec le code forbidden : la clé n'a pas le droit nécessaire pour cette requête. Créez-en une nouvelle avec le bon droit.

• 403 avec le code API_ORGANIZATION_SUSPENDED : l'organisation est suspendue.

• 403 avec le code READ_ONLY : l'abonnement présente un retard de paiement ou a pris fin. La lecture reste possible, la modification non. Le propriétaire règle cela sous Abonnement.

• 429 avec le code API_RATE_LIMITED : plus de 120 requêtes par minute avec cette clé. Attendez le nombre de secondes indiqué dans l'en-tête Retry-After.

• « Votre rôle n'a aucun droit de l'application à donner à une clé. » Demandez au propriétaire.

• « Une organisation a au plus 50 clés API. » Supprimez les clés que vous n'utilisez plus.

Avec votre assistant IA

Un assistant ne crée pas de clés, et ne lui en confiez jamais dans une conversation. Demandez-lui plutôt un script : « Écris un script qui récupère mes offres d'emploi dans Kintsu avec l'API. Lis la clé dans la variable d'environnement KINTSU_API_KEY. »

Pour aller plus loin : L'API pour les développeurs et la référence.

Vérifié le 4 novembre 2026.