Gestion des clés API
Format du token, processus de création, 8 portées de permissions (scopes), cycle de vie, analyse d'usage, bonnes pratiques de sécurité.
La clé API est votre seul identifiant pour communiquer avec la plateforme ouverte Braidrun. Chaque clé comporte un ensemble de portées (portée d'autorisation) et un jeton. En cas de perte ou de fuite, la nouvelle création sera immédiatement révoquée.
Format du jeton
dyk_<id>_<secret>
例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789dyk_— Préfixe de marque pour rendre l'outil d'analyse secrète / de désensibilisation des journaux git identifiable<id>— Identifiant public base62 de 16 caractères, utilisable comme clé de recherche (non sensible)<secret>— Secret aléatoire de 32 octets, encodage base64url (sensible, aucun journal/message d'erreur autorisé à être téléchargé)
Lors de la génération d'une clé API, le jeton d'origine n'est affiché qu'une seule fois dans la boîte de dialogue de création. Après la fermeture, le serveur conserve uniquement le hachage Argon2id et ne peut pas réviser le texte original. Veuillez copier et enregistrer dès maintenant dans votre outil de gestion de clés (1Password/Vault/Doppler/GitHub Secrets/etc).
Créer une clé API
- Visitez la console → Paramètres du compte → Clé API
- Cliquez sur "Nouvelle clé API"
- Remplissez : nom (pour identification), liste de champ d'application, durée de validité (permanente / 30 jours / 90 jours / 1 an)
- Cliquez sur "Générer la clé" → Copier le jeton maintenant
Portées
Les Scope sont des permissions à granularité fine, au nombre de 8 : 7 peuvent être accordées en libre-service, CLUSTER_ADMIN est réservée aux administrateurs. Accordez le moins de permissions possible à une Key, selon le principe du moindre privilège.
| Scope | que peut-on faire | Scénarios courants |
|---|---|---|
WEBHOOK_TRIGGER | Déclenchez le Webhook lié à cette clé | GitHub Push → Flux de travail ; rappel du système métier en amont |
APPROVAL_RESPOND | Approuver / rejeter les étapes manual_approval — couvre les Webhook d'approbation et les endpoints d'approbation v1 (/api/v1/approvals/*, incluant la liste des approbations en attente, la lecture des détails et la soumission du formulaire d'approbation modifié) | Liens d'approbation en un clic par e-mail / Slack ; intégration avec des systèmes d'approbation externes |
WORKFLOW_READ | Répertorier/lire les définitions de flux de travail | Afficher la liste des workflows actuels dans un tableau de bord externe |
WORKFLOW_EXECUTE | Démarrer les workflows via API (remplacement du mode webhook) | Intégration du SDK ; tests automatisés ; tâches par lots |
EXECUTION_READ | Statut d'exécution de la requête / lecture du résultat complet | Résultats de l'exécution du backflow vers l'entrepôt de données/BI d'entreprise |
EXECUTION_CANCEL | Annuler une exécution en cours | Bouton "Stop" sur le panneau de gestion/disjoncteur de secours |
ARTIFACT_READ | Répertorier les produits d'exécution/obtenir le lien de téléchargement | Archiver les rapports dans le stockage d'objets ; transmettre les résultats aux systèmes en aval |
CLUSTER_ADMIN | Réservé aux administrateurs : lecture de l'état du cluster, gestion des politiques d'autoscaling. Seuls les administrateurs peuvent l'accorder ; ce scope est automatiquement retiré lorsqu'un non-administrateur crée une Key | Compte de service d'exploitation pour les déploiements sur site |
Cycle de vie
- créer — Libre-service utilisateur ; la portée + la période de validité sont décidées par vous
- Utiliser — Chaque appel réussi accumule automatiquement l’utilisation et met à jour l’horodatage lastUsedAt.
- Revoke — Les utilisateurs peuvent cliquer sur « Révoquer » sur la page « Clé API » à tout moment ; idempotent
- Expire — expiresAt expire immédiatement à l'arrivée ; aucune révocation active n'est requise
Analyse posologique
Pour chaque clé, cliquez sur « Utilisation » dans le tableau « Clé API » et une analyse graphique apparaîtra :
- Nombre cumulé d'appels + dans la fenêtre (7/30/90/180 jours en option)
- Jour de pointe (quel jour a le plus d'appels)
- Graphique linéaire des appels quotidiens
- Diagramme circulaire de distribution des points de terminaison d'appel (webhook.trigger/workflow.execute/etc)
- Heure de la dernière utilisation
L'utilisation ne compte que les réponses réussies (HTTP 2xx). Les échecs d’authentification/demandes à débit limité ne sont pas comptés.
Meilleures pratiques de sécurité clés
- Utilisez des clés indépendantes pour chaque environnement (production/staging/local) - seul l'environnement affecté sera révoqué en cas d'incident
- Chaque intégration externe utilise une clé distincte : utilisez "Utilisation" pour voir quelle intégration est utilisée
- Ne soumettez jamais de jeton au référentiel de code
- Injecter en tant que secret chiffré dans CI/CD ; ne pas imprimer dans les journaux
- Observez que l'heure "récemment utilisée" est différente de vos attentes → révoquez immédiatement et vérifiez les journaux
- Les clés données aux partenaires à court terme doivent être définies sur expiresAt (recommandé dans les 90 jours)