---
title: Piloter depuis un outil externe
description: Scénario complet avec une clé API à droits restreints, une demande d'exécution idempotente par curl, son suivi, l'export de consommation et la mise en attente pendant un arrêt global.
---

# Piloter depuis un outil externe

L'équipe d'Atelier Exemple veut déclencher et suivre les exécutions depuis son outil de suivi interne. Dominique crée une clé API personnelle limitée à ce besoin et écrit les appels.

## Objectif

Démarrer une exécution sur une issue, suivre son état et lire la consommation du projet depuis un script, sans jamais exposer la clé.

## Rôles nécessaires

| Personne | Rôle | Intervient pour |
| --- | --- | --- |
| Dominique | Opérateur du projet **Site vitrine** | Créer la clé et l'utiliser |

Une clé ne donne jamais plus que les droits actuels de la personne qui l'a créée. Pour démarrer une exécution, il faut donc au moins le rôle Opérateur.

## Prérequis

- Le dépôt est actif, rattaché et surveillé, et l'issue visée est ouverte et suivie par la plateforme. Voir [Embarquer une équipe sur un projet](02-embarquer-une-equipe-sur-un-projet.md).
- L'outil sait conserver un secret (gestionnaire de secrets, variable protégée de CI).

## Étapes

### Créer une clé à droits restreints

1. Dominique fait une [vérification récente](../01-prise-en-main/05-session-et-verification-recente.md).
2. Dans la barre **Supervision**, il ouvre **Mes clés API**, carte **Créer une clé**.
3. **Libellé** : `outil-suivi-site-vitrine`. **Durée en jours** : `30`.
4. **Projets** : il coche seulement **Site vitrine**.
5. **Droits de la clé** : il coche **Lire les projets**, **Lire les dépôts**, **Lire les exécutions**, **Démarrer une exécution** et **Lire la consommation**. Rien d'autre.
6. Il clique sur **Créer la clé**. Le **Secret de la clé** s'affiche une seule fois : il le copie dans le gestionnaire de secrets, puis clique sur **Masquer le secret**.

Voir [Clés API personnelles](../07-integration-api/02-cles-api-personnelles.md) et [Authentification et scopes](../07-integration-api/03-authentification-et-scopes.md).

### Retrouver le projet et le dépôt

7. Le script lit la clé depuis une variable d'environnement, jamais depuis le code :

```bash
export MAINTAIN_API_KEY="<secret lu depuis le gestionnaire>"
curl -sS https://maintenance.maintain.example/api/v1/projects \
  -H "Authorization: Bearer $MAINTAIN_API_KEY"
```

8. Avec l'identifiant du projet, il liste les dépôts pour obtenir `repositoryId` :

```bash
curl -sS https://maintenance.maintain.example/api/v1/projects/<projectId>/repositories \
  -H "Authorization: Bearer $MAINTAIN_API_KEY"
```

### Démarrer une exécution, sans doublon

9. Il demande l'exécution de l'issue n° 42, avec une clé d'idempotence stable (8 à 128 caractères) :

```bash
curl -sS -i -X POST https://maintenance.maintain.example/api/v1/projects/<projectId>/runs \
  -H "Authorization: Bearer $MAINTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-vitrine-issue-42" \
  -d '{"repositoryId":"<repositoryId>","issueNumber":42}'
```

La réponse est `202` avec l'en-tête `Location: /api/v1/runs/<runId>`. Si le script renvoie la même requête (coupure réseau, nouvel essai), la même réponse est rejouée pendant 24 heures, avec l'en-tête `Idempotent-Replayed: true`. Une seule exécution est créée.

Notez aussi l'en-tête `X-Correlation-Id` : il retrouve la demande dans le [journal des actions](../06-administration-et-supervision/06-journal-des-actions.md).

### Suivre l'exécution

10. Le script interroge l'exécution à intervalle raisonnable :

```bash
curl -sS https://maintenance.maintain.example/api/v1/runs/<runId> \
  -H "Authorization: Bearer $MAINTAIN_API_KEY"
```

Le champ `status` évolue, par exemple de `queued` à `running`, puis `prepared` (correctif prêt) ou `needs_input` (précisions requises). Les réponses aux questions se font dans l'interface : elles n'ont pas de route d'API.

### Lire la consommation

11. En fin de mois, le script exporte la consommation du projet :

```bash
curl -sS https://maintenance.maintain.example/api/v1/projects/<projectId>/usage \
  -H "Authorization: Bearer $MAINTAIN_API_KEY"
```

Un usage inconnu reste signalé comme tel, jamais converti en zéro. Voir [Comprendre la consommation](../05-rapports-usage-et-couts/03-comprendre-la-consommation.md).

### Réagir à un arrêt global

12. Pendant un incident, l'Administrateur active l'[arrêt global](../06-administration-et-supervision/09-arret-global.md). Une nouvelle demande d'exécution n'est pas refusée : elle répond `202`, comme d'habitude, avec en plus le champ `waiting` :

```json
{
  "id": "<runId>",
  "status": "queued",
  "repositoryId": "<repositoryId>",
  "issueNumber": 42,
  "waiting": "organization_stop"
}
```

L'exécution reste en file et démarrera une seule fois après la levée. Tant qu'elle attend, `GET /api/v1/runs/<runId>` porte le même champ `waiting`. Le script n'a rien à redemander : il signale l'attente et continue de suivre l'exécution. Un rejeu avec la même clé d'idempotence, pendant ou après l'arrêt, renvoie le même identifiant sans créer de second travail. Une demande d'audit se comporte de la même façon.

## Résultat attendu

- Une exécution créée une seule fois, même si la demande arrive pendant un arrêt global, visible dans la [File de travail](../06-administration-et-supervision/05-file-de-travail.md).
- Chaque appel inscrit au journal des actions avec le type d'acteur **Clé API**, le compte de Dominique et l'identifiant de la clé.
- La clé apparaît dans l'[inventaire des clés](../06-administration-et-supervision/07-inventaire-des-cles-api.md) avec sa date de dernière utilisation.

## Si ça bloque

| Code | Cause | Que faire |
| --- | --- | --- |
| `401` | Clé absente, invalide, expirée ou révoquée, ou compte inactif. | Vérifiez la variable, créez une nouvelle clé. |
| `403` | Droit absent de la clé, ou rôle devenu insuffisant. | Vérifiez les droits de la clé et le rôle sur le projet. |
| `404` | Projet hors de la clé ou hors de vos droits. | Vérifiez le projet coché à la création. |
| `409` | Issue fermée, exécution déjà existante, ou clé d'idempotence réutilisée avec un autre corps. | Lisez le champ `error`. |
| `429` | Quota de 120 requêtes par minute, par clé et par projet, dépassé. | Attendez la durée indiquée par `Retry-After`. |

Voir aussi [Erreurs](../07-integration-api/05-erreurs.md), [Idempotence et quotas](../07-integration-api/04-idempotence-et-quotas.md) et les [recettes](../07-integration-api/06-recettes.md).

> [!TIP]
> Un agent IA peut découvrir l'API seul : le site de documentation publie le contrat OpenAPI et un index lisible par machine à des adresses stables. Voir [Ressources pour agents IA](../07-integration-api/07-agent-ia.md).

## Pour continuer

Pour la référence complète des routes, voyez [Intégration API](../07-integration-api/01-vue-d-ensemble.md).
