Clés API et jetons d’accès

Une clé API est le moyen par lequel vos programmes accèdent à l’API LinkHarbor. Elle appartient à un espace de travail, pas à une personne, et peut faire exactement ce que vous lui autorisez via les portées. Pour les appels eux-mêmes, vous échangez la clé contre un jeton d’accès de courte durée.

#Qui peut créer des clés API ?

• Les propriétaires et les admins de l’espace de travail – les éditeurs et les lecteurs ne voient que la carte « Applications connectées » sous « Callback et API »
• À partir de Creator Pro ; avec Creator Free, la carte indique « Les clés API sont disponibles à partir de Creator Pro. »
• Actives en même temps : jusqu’à 5 clés avec Creator Pro, jusqu’à 20 avec Creator Agency, jusqu’à 50 avec Enterprise

Une fois la limite atteinte, la création d’une clé échoue avec 409 limit_reached. Supprimez d’abord une clé dont vous n’avez plus besoin.

#Créer une clé API

1. Ouvrez « Callback et API » dans la navigation
2. Dans la carte « Clés API », cliquez sur « + Créer une nouvelle clé »
3. Sous « Nom (facultatif) », saisissez un nom qui vous permettra de reconnaître la clé, par exemple « Pipeline CI/CD » ou « Synchro boutique »
4. Sous « Portées », choisissez « Lecture » ou « Écriture » pour chaque domaine
5. Cliquez sur « Créer la clé »
6. Copiez immédiatement le « Secret de la clé (privé) » et conservez-le en lieu sûr
7. Fermez la boîte de dialogue – vous retrouvez l’ID de la clé à tout moment dans la liste

« Nom (facultatif) »

Jusqu’à 64 caractères. Sans nom, la clé apparaît dans la liste comme « Clé API #ID ».

« Portées »

Au moins une est requise. « Écriture » inclut automatiquement « Lecture » pour le même domaine. Les statistiques et les paiements des soutiens sont en lecture seule, les modèles d’espace de travail en écriture seule. Toutes les portées sont expliquées dans Les portées en détail.

« Secret de la clé (privé) »

Commence par lt_ et n’est affiché qu’une seule fois (« ⚠️ Visible une seule fois — copiez-le maintenant ! »). LinkHarbor n’en enregistre qu’un hash et ne peut plus vous l’afficher ensuite.

« ID de clé : »

16 caractères composés de chiffres et des majuscules A–F, par exemple 6F668EA6598B0692. Il n’est pas secret et apparaît dans la liste avec un bouton de copie.

#La liste des clés

Chaque clé active affiche son nom, le statut « Actif », l’ID de la clé, ses portées, « Créée : » et « Dernière utilisation : » ou « Pas encore utilisée ». L’heure de dernière utilisation est mise à jour à chaque appel effectué avec la clé, au plus une fois par minute. « ↺ Actualiser » recharge la liste.

#Échanger la clé contre un jeton d’accès

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

Le jeton d’accès. Vous l’envoyez avec chaque requête sous la forme Authorization: Bearer <token>.

expires_in

Validité en secondes : 900, soit 15 minutes. Il n’y a pas de jeton de rafraîchissement – une fois expiré, récupérez simplement un nouveau jeton avec l’ID et le secret de la clé.

Le jeton représente l’espace de travail et porte exactement les portées de la clé. Il n’a pas de rôle comme une personne : les endpoints que le tableau de bord réserve aux propriétaires et aux admins (membres, facturation, gestion des domaines, webhooks, réglages de l’espace de travail) sont toujours refusés aux jetons issus de clés API. Les exceptions sont les liens courts et les modèles d’espace de travail, qui fonctionnent avec la portée correspondante, ainsi que la lecture des secrets de callback (sans le secret en clair) avec read:workspaces.

#Échecs et verrouillage

Avec api_key_locked, le temps restant figure dans details.retry_after_sec. Un échange réussi remet le compteur à zéro.

#Supprimer et remplacer une clé

1. Cliquez sur « Supprimer » à côté de la clé
2. Tapez DELETE pour confirmer
3. Cliquez sur « Supprimer définitivement »

La clé cesse immédiatement de fonctionner – les jetons d’accès déjà émis cessent aussi de fonctionner dès ce moment et reçoivent 401 invalid_token. Il n’y a pas de bouton de rotation. Pour changer de clé, créez une nouvelle clé, faites basculer votre programme dessus, puis supprimez l’ancienne.

#Quand l’offre baisse

Si l’espace de travail passe à Creator Free, toutes les clés API sont révoquées. S’il passe à une offre avec moins de clés, les plus récentes sont conservées et les autres révoquées. Les clés révoquées ne reviennent pas après une mise à niveau ultérieure – vous en créez alors de nouvelles. Les propriétaires reçoivent un e-mail listant les fonctions désactivées. Plus d’infos dans Résiliation et rétrogradation.

#Sécurité

• Ne conservez le secret que dans un gestionnaire de secrets ou dans des variables d’environnement, jamais dans le code source ni dans un dépôt Git
• Ne l’utilisez jamais dans du code exécuté dans le navigateur ou dans une app sur l’appareil de l’utilisateur
• Créez une clé distincte pour chaque application, avec le moins de portées possible
• Supprimez immédiatement les clés dont vous n’avez plus besoin
• En cas de soupçon de fuite : supprimez la clé et créez-en une nouvelle