Cles API et scopes
Comment choisir les scopes de cle API projet et donner acces a BernOps aux machines.
Sur cette page
Les cles API projet permettent a des systemes externes d'operer dans un seul projet BernOps sans partager une session utilisateur. Ce sont des bearer tokens, donc traitez-les comme des identifiants de production.
Choisir l'appelant
Utilisez un JWT utilisateur quand une personne utilise l'interface et effectue des actions de gestion. Utilisez une cle API projet quand une machine a besoin d'un acces repetable.
Bons cas d'usage de cle API :
- Un pipeline CI execute des jobs enregistres.
- Un worker de file reclame et termine des elements.
- Un job d'automatisation externe envoie logs, etapes, metriques et pieces jointes.
- Un serveur MCP lit l'etat du projet et declenche du travail approuve.
- Un agent du tableau reclame le travail A faire, renouvelle son bail et soumet le resultat a la revision humaine.
Les scopes sont des capacites
Les processus SDK externes doivent utiliser une cle ingest-runner liee au job avec uniquement les scopes d'ecriture requis. Consultez le demarrage externe du SDK d'automatisation ; les jobs SDK Playwright natifs n'ont besoin d'aucune cle API.
Les scopes expriment ce qu'une cle peut faire dans son projet. Preferez le preset le plus etroit qui couvre le besoin.
| Preset ou famille de scopes | Role typique |
|---|---|
cicd-driver | Executer des jobs existants et lire l'etat des executions depuis la CI. |
ingest-runner | Reporter logs, etapes, metriques et pieces jointes d'executions externes. |
queue-worker | Lire les files, reclamer des elements et reporter leur progression. |
board-agent | Lire et modifier le travail du projet, acquerir des reclamations cloturees et soumettre le travail en revision. |
mcp-agent | Inspecter l'etat du projet et declencher du travail limite. |
variables:use | Permettre aux executions lancees par cle API de recevoir les variables runtime projet. |
L'automatisation du tableau utilise work_items:read pour decouvrir le travail, work_items:write pour creer ou modifier les elements de planification et work_items:claim pour reclamer, renouveler, liberer et soumettre. Le statut d'un element reste independant du statut des executions.
Si une requete retourne Insufficient API key scope, la cle est bien authentifiee mais n'a pas la capacite requise par l'endpoint ou le chemin d'execution.
Variables runtime et cles
Le scope variables:use est special. Il ne permet pas de lire les secrets depuis l'API. Il permet seulement aux executions lancees par cette cle de recevoir les variables projet dans le processus worker.
C'est utile quand une cle CI lance un job Playwright enregistre qui a besoin de HAPPY_PATH_QUEUE_API_KEY, TARGET_TENANT ou d'autres valeurs specifiques au projet.
Les presets qui peuvent creer des executions arbitraires, comme ingest-runner et queue-worker, n'incluent pas variables:use par defaut. Ajoutez-le manuellement seulement quand ce runner doit recevoir les secrets projet.
Strategie de rotation
Faites pivoter les cles plutot que les supprimer et recreer quand vous avez besoin d'un deploiement sans interruption.
- Creez ou faites pivoter la cle depuis la page des cles API.
- Stockez la nouvelle valeur dans votre gestionnaire de secrets ou variables CI.
- Deployeez-la sur chaque worker, pipeline ou host MCP.
- Verifiez le nouveau trafic, puis laissez l'ancienne valeur expirer ou revoquez-la.
Reference API
La page Reference API documente les chemins exacts, modes d'auth, corps de requete et formes de reponse. Utilisez-la pour implementer une integration apres avoir choisi la cle et les scopes.
Ouvrir la Reference API.