Appeler Grace depuis un hook

Créer une clé API de projet et l'utiliser dans un hook d'agent, un script CI ou une automatisation locale.

Les agents IA permettent d'exécuter des hooks à différents moments : avant le démarrage, avant ou après un appel d'outil, à la fin d'une tâche. Ces scripts sont headless — pas de navigateur, donc pas de flux OAuth possible.

Une clé API de projet leur donne un moyen d'appeler les outils Grace avec un simple en-tête Authorization.

Créer une clé

Ouvrez votre projet → onglet Paramètres → section Clés API.
Créer une clé, puis :
- un nom qui dit son usage (« hook validate — poste de travail ») : c'est le seul repère dont vous disposerez plus tard, la valeur n'étant plus consultable ;
- les outils que la clé pourra appeler — cochez le strict nécessaire ;
- une expiration, facultative.
Copiez la valeur immédiatement. Elle est affichée une seule fois. Elle n'est pas stockée en clair : personne, pas même un administrateur de la plateforme, ne pourra la relire.

Perdue, une clé ne se retrouve pas — elle se révoque et se recrée.

Ce qu'une clé peut appeler

Outil	Méthode et route	À quoi ça sert dans un hook
`prepare_task`	`POST /api/prepare-task`	Préparer les conventions au début d'une tâche
`validate`	`GET /api/validation/playbook`	Obtenir le playbook d'audit avant de conclure
`record_validation`	`POST /api/validation/reports`	Enregistrer les verdicts et preuves des talents vérifiés
`deepen`	`GET /api/search` et `POST /api/talents/get`	Chercher un talent, ou lire le contenu de l'un d'eux
`doctor`	`GET /api/doctor`	Diagnostiquer la configuration
`catalog`	`GET /api/catalog`	Lister le catalogue
`discover`	`GET /api/discovery/playbook`	Lire la procédure de découverte
`install`	`PATCH /api/projects/:id/talents`	Modifie la sélection de talents

install et record_validation écrivent. Un hook qui ne fait que préparer une tâche ou relire un audit n'en a pas besoin. Accordez record_validation uniquement au processus chargé de persister les verdicts de revue, et install uniquement à celui qui installe ou désactive des talents.

deepen couvre les deux routes de l'outil grace_deepen, qui aiguille sur ses paramètres. Après grace_prepare_task, réutilisez son resolutionId : { resolutionId, uris: [{ uri }, …] } lit jusqu'à 20 fichiers en un appel, { resolutionId, uri } en lit un et { resolutionId, query } cherche des talents. Regroupez les adresses utiles par lots séquentiels de 20 maximum. Grace peut ainsi relier préparation, approfondissements et revue sans rattachement approximatif.

Aucun autre en-tête n'est nécessaire : la clé désigne son projet. Si vous envoyez malgré tout un x-grace-project, il est ignoré — une clé ne peut pas être redirigée vers un autre projet.

Appeler

curl -s -X POST https://<votre-domaine>/api/prepare-task \
  -H "Authorization: Bearer $GRACE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"talentIds":["grace.architecture.hexagonal"],"language":"typescript"}'

Exemple — hook de fin de tâche qui appelle `validate`

Conservez le resolutionId renvoyé au début de la tâche, puis transmettez-le au playbook :

#!/usr/bin/env bash
set -euo pipefail

: "${GRACE_KEY:?clé API absente}"
: "${GRACE_URL:?URL Grace absente}"
: "${GRACE_RESOLUTION_ID:?resolutionId absent}"

# Demander le plan même si l'arbre de travail est propre : la revue scellée peut couvrir des commits ou des fichiers non suivis.

curl -sS --get "$GRACE_URL/api/validation/playbook" \
  -H "Authorization: Bearer $GRACE_KEY" \
  --data-urlencode "resolutionId=$GRACE_RESOLUTION_ID"

Le processus qui possède le scope record_validation envoie ensuite un submissionId stable, les verdicts des règles Grace vérifiables et ceux des Talents Custom à POST /api/validation/reports. Une clé portant uniquement validate reçoit 403 insufficient_scope sur cette route.

Enregistrez le premier rapport exhaustif avant de corriger une violation bloquante. Après la correction et la nouvelle revue, envoyez un second rapport avec un nouveau submissionId. Ne réutilisez le premier identifiant que pour retenter exactement le même rapport.

Exemple — hook de début de tâche qui appelle `prepare_task`

#!/usr/bin/env bash
# Injecte les conventions du projet dans le contexte de l'agent, avant qu'il écrive du code.
set -euo pipefail

# Les identifiants viennent du répertoire des expertises désignables du projet
# (GET /api/prepare-task/designable).
talents="${1:?nommez au moins une expertise, séparées par des virgules}"

curl -sS -X POST "$GRACE_URL/api/prepare-task" \
  -H "Authorization: Bearer $GRACE_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg t "$talents" '{ talentIds: ($t | split(",")) }')"

Désignez tout ce que le travail touche, et conservez le resolutionId de la réponse : il fige les talents et les versions privées servis, qui sont exactement ceux que le playbook d'audit couvrira. Ce qui n'est pas désigné n'est ni servi ni relu.

Où mettre la clé

Dans une variable d'environnement, jamais dans un fichier committé. Le préfixe grc_pk_ est distinctif : il permet à un scanner de secrets (gitleaks, trufflehog) de repérer une fuite.

Poste de développement : votre profil shell, ou le gestionnaire de secrets de l'agent.
CI : les secrets du dépôt ou de l'organisation.

Comprendre les refus

Réponse	Ce qui se passe
`401 invalid_token`	Clé inconnue, révoquée, expirée — ou fonctionnalité désactivée. La réponse est volontairement la même dans les quatre cas
`403 insufficient_scope`	La clé n'autorise pas cet outil. `requiredScope` indique lequel il faut ; recréez une clé en le cochant
`403` (organisation)	L'organisation du projet n'est plus approuvée
`403 not_a_member`	Le porteur de la clé n'est plus membre de l'organisation
`404`	Le projet n'existe plus

Les droits sont réévalués à chaque appel : une clé ne fige rien. Si vous quittez l'organisation, vos clés cessent de fonctionner ; si vous y revenez, elles refonctionnent.

Révoquer

Depuis la même section, Révoquer. L'effet est immédiat : l'appel suivant est refusé.

Tout membre du projet voit les clés du projet et peut les révoquer, y compris celles créées par quelqu'un d'autre. Une clé posée dans un hook ou une CI est un fait d'exploitation du projet, pas un secret personnel — et lors d'une fuite, la révocation ne doit pas attendre le retour de son auteur.

Ce que les clés ne font pas

Gérer d'autres clés : la création et la révocation exigent une session web. Une clé fuitée ne peut pas se perpétuer.
Accéder au dashboard : une clé n'ouvre que les outils qu'elle nomme, sur son projet.
Remplacer OAuth pour un usage interactif : pour brancher un agent à Grace, utilisez l'URL MCP du projet, qui ne contient aucun secret et peut être committée.

Appeler Grace depuis un hook

Sur cette page