Créer et gérer les clés API
Une clé API autorise un programme à accéder à une organisation Boldo. Chaque clé possède son type et ses rôles ; l’appartenance de son titulaire conditionne également l’accès.
Votre offre doit inclure l’API. Les Éditeurs gèrent leurs propres clés ; les Administrateurs et le Propriétaire peuvent aussi gérer celles des autres membres.
Créer et conserver une clé
- Sélectionnez l’organisation cible et ouvrez Gestion de l’organisation > API.
- Dans Clés API, cliquez sur Créer une clé API.
- Saisissez un Nom identifiant l’intégration. Ajoutez éventuellement une Description.
- Choisissez le Type : Lecteur, Éditeur ou Administrateur, parmi les options disponibles. Le choix initial est Lecteur.
- Sélectionnez les Rôles nécessaires. Laissée vide, la sélection donne à la clé vos rôles si vous êtes Éditeur avec des rôles, et les droits Sans rôle sinon.
- Cliquez sur Créer la clé.
- Dans Clé API créée, copiez la valeur complète dans le stockage de secrets de votre intégration.
- Cliquez sur J’ai sauvegardé ma clé, puis testez une lecture API limitée.
Le nom accepte jusqu’à 100 caractères et la description jusqu’à 500. Propriétaire n’est pas un type de clé. Le formulaire ne propose pas de date d’expiration.
La valeur complète apparaît uniquement à la création et après une régénération, dans une fenêtre que seul J’ai sauvegardé ma clé ferme. La liste conserve son préfixe et sa configuration, mais ne permet pas de retrouver le secret. Si vous le perdez, régénérez la clé. N’incluez pas la clé dans des captures, tickets ou exemples de requêtes partagés.
Comprendre les droits effectifs
Le type effectif est le plus faible entre celui de la clé et celui de son titulaire. Une clé Administrateur appartenant à un Éditeur agit donc comme Éditeur.
Une clé sans rôle utilise les droits Sans rôle ; elle n’hérite pas des rôles de son titulaire. Sans rôle compte comme un rôle à part entière : un Éditeur qui a des rôles ne peut pas l’attribuer, il ne peut donc pas vider les rôles d’une clé, et une clé qu’il crée sans rôle reçoit les siens. Les rôles affectés à la clé déterminent son accès aux données métier. Ils ne sont pas continuellement limités aux rôles actuels du titulaire. Un Administrateur peut attribuer des rôles que le titulaire ne possède pas personnellement, ou aucun. Un Éditeur ne peut attribuer que ses propres rôles et un type au plus égal au sien. Les rôles attribués par un Administrateur hors du périmètre de l’Éditeur restent protégés lorsque celui-ci modifie la clé. Par l’API, une clé crée ou modifie des clés dans la limite de son propre type et de ses propres rôles, quel que soit son type, Sans rôle compris : une clé limitée à certains rôles ne peut pas obtenir les autres rôles de son titulaire, et une clé qu’elle crée sans rôle reçoit les siens.
Une clé Administrateur respecte toujours les droits métier sur les actifs, propriétés et domaines d’accès. Choisissez les droits minimaux nécessaires à l’intégration ; consultez le modèle d’accès pour distinguer leur portée.
Modifier ou transférer une clé
- Retrouvez la clé dans Clés API, grâce à son nom, son préfixe et sa Dernière utilisation.
- Ouvrez son menu Actions et choisissez Modifier.
- Modifiez le nom, la description, le type ou les rôles selon vos autorisations.
- Comme Administrateur ou Propriétaire, utilisez Propriétaire pour transférer la clé à un autre membre de cette organisation si nécessaire.
- Cliquez sur Modifier la clé.
- Testez à nouveau l’intégration, notamment après changement du titulaire ou des rôles.
Modifier la configuration ne révèle ni ne remplace le secret. Le transfert conserve les rôles affectés, mais le type du destinataire peut réduire le type effectif.
Renouveler ou révoquer l’accès
Régénérez une clé pour remplacer son secret, par exemple après une fuite. La clé conserve son nom, son type, ses rôles et son titulaire ; seuls le secret et son préfixe changent.
- Ouvrez Actions > Régénérer la clé sur la clé.
- Dans Régénérer la clé API, vérifiez le préfixe et cliquez sur Régénérer.
- Dans Clé API régénérée, copiez la nouvelle valeur dans le stockage de secrets de l’intégration, puis cliquez sur J’ai sauvegardé ma clé.
- Testez l’intégration. Dernière utilisation reste vide jusqu’au premier usage du nouveau secret.
L’ancien secret cesse de fonctionner immédiatement, sans délai de grâce : les requêtes qui l’envoient encore reçoivent HTTP 401 jusqu’à la mise à jour de l’intégration. Pour basculer sans interruption, créez une seconde clé, déployez-la, puis supprimez l’ancienne.
Un Éditeur régénère ses propres clés, y compris une clé qu’un Administrateur lui a transférée avec des rôles qu’il ne possède pas : le transfert lui confie la clé. Les Administrateurs et le Propriétaire régénèrent toutes les clés. Une intégration peut aussi régénérer sa propre clé avec POST /api-keys/{id}/rotate ; la réponse est alors la seule copie du nouveau secret. Par l’API, une clé n’en régénère une autre que dans la limite de son propre type et de ses propres rôles.
Pour révoquer une clé :
- Ouvrez Actions > Supprimer sur la clé.
- Vérifiez la confirmation Supprimer la clé API.
- Cliquez sur Supprimer.
- Si l’intégration est passée à une autre clé, vérifiez que cette connexion fonctionne toujours.
La suppression révoque les requêtes suivantes utilisant cette clé. Elle ne retire pas les données précédemment créées par l’intégration. Une clé supprimée ne peut pas être récupérée.
Si le titulaire perd toutes ses méthodes de connexion actives dans l’organisation, ses clés cessent de fonctionner. La suspension conserve les clés : une réactivation peut rétablir leur utilisation. Retirer l’appartenance supprime les clés associées. Désactiver une seule méthode ne coupe pas les clés si une autre reste active.
Les appels vérifient aussi l’état de l’organisation, la disponibilité de l’API et les adresses IP autorisées. Ils ne répètent pas une connexion interactive SSO ou à deux facteurs à chaque requête. Pour les erreurs, utilisez le tableau de diagnostic API.